README
¶
Tenant component galleries
The admin module serves the interactive gallery at /admin/_gallery. Sign in
with gallery:read (included by the administrator's wildcard). The default
composition shows Core examples only on the operator tenant. Customer tenants
receive 403 until the application supplies admin.Deps.Storybook.
The Go explorer works without a JavaScript build. To run actual Storybook.js,
follow the Storybook adapter instructions.
The application composition owns this selector. Read the tenant and principal
already established in context.Context; select examples from the same resolved
product/module composition used by the application. Return export.Storybook with
that composition's Examples, Theme and stylesheet Extra values. Reuse an
existing product Design() contribution rather than maintaining another registry.
Return a problem.Problem with status 403 for a tenant or caller without access.
An empty example collection remains empty, including for the operator.
Never choose a tenant from a query parameter, accept arbitrary example definitions
from the browser, or return the union of every tenant's examples and hide links.
The selector is authoritative for the index, /preview, /export, navigation
and every file under /storybook/. Its optional Files contains an immutable
Storybook.js build for exactly that composition; mismatched builds are refused.
Direct requests for unpublished example IDs return 404. The endpoints require
the gallery permission before selecting content; responses containing the selected
composition are not cached. Keep private assets in application routes with the
same authorization or embed them in the examples. The shared public asset tree
contains the installation stylesheet and framework scripts, so tenant-specific
assets and CSS must not be placed there.
Choose an example and change its typed controls. The preview updates automatically after typing pauses or a selection changes, keeping focus in the controls. Invalid input preserves the last valid preview; Apply preview retries an update. The server patches the captured Go invocation; property types, declared allowed values and documentation come from its Props. Go properties copies the current Go declaration. Pass it to the component constructor, adding documented slots in trusted Go composition. Slot callbacks and arbitrary markup are not browser inputs.
The isolated preview supports keyboard interaction, native modal focus, light/dark themes and 320/768/1280px viewports. Its HTTP content security policy also sandboxes the direct preview URL: forms, network requests, storage and access to the parent document are blocked. Lazy-loaded examples therefore require application journey tests for their network behavior. Narrow preview widths scroll inside the gallery.
In an application, load a deferred modal panel into its existing root with
HTMXProps{Get: panelPath, Target: "#server-modal", Swap: "innerHTML"} on the
trigger. Set the root's ID to server-modal, Deferred: true and
OpenOnSwap: true. The root opens after the swap settles and clears on close.
The explicit swap keeps the dialog root; the application otherwise defaults to
replacing the target element. Give multiple tabs or dialogs distinct IDs.
ModalForm closes its owning dialog after a successful 2xx response, including
when the response replaces the form. Validation and failed requests keep it open;
a delayed response from an earlier opening cannot close a reopened dialog.
Section, SectionHeader and Hero compose the existing components. Heading
separates semantic Level from visual Size; Grid accepts SM, MD and LG
column overrides. design.Theme.Shape controls button, card and modal radii beside
the existing colors and typography; the same values appear in CSS and design exports.
For local verification, follow the contribution guide.
make check covers tenant isolation and exported contracts; make e2e covers
gallery controls, responsive layout, actual widget interactions and selected axe
checks in both themes. These checks do not establish native editor fidelity or
replace a screen-reader review. New product integrations must supply their selector
and repeat these checks against their own examples and private asset routes.
Documentation
¶
Overview ¶
Package admin is the shell: the pages a person sees, as opposed to the routes a program calls.
It writes almost no screens. ARCHITECTURE.md's eighth idea is that list, detail and form come from an entity's schema, and kit/httpx carries that schema for every resource kit/rest mounted. The generated screens are ui/screens'; this module composes them with its own chrome, frame and navigation, adds the five pages no schema describes — the dashboard, the health page, the sign-in page, the gallery and the tenant switcher — and serves the same knowledge as JSON at /api/v1/admin/resources for a shell that is not a browser. A sixth hand-written page arrives only when an interaction cannot be derived.
It is composed last, and that is load-bearing rather than tidy: kit/app calls each module's Routes in composition order, so a module mounted after this one registers a resource whose screens were already generated — which is to say, were not.
Index ¶
Constants ¶
const PermissionGalleryRead = "gallery:read"
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Deps ¶
type Deps struct {
// Modules is the composition, for navigation. The shell draws the sidebar
// from every module's Nav, so it needs the list main built; a copy
// maintained here would be a second answer to "what is in this
// application", and the one that goes stale.
Modules []module.Module
// Authorize is the same value the kernel enforces with. The sidebar shows a
// link only when the caller may follow it, and asking the authorizer is
// what makes that the same answer the route would give — a nav filter with
// rules of its own is a menu that lies in one direction or the other.
Authorize httpx.Authorizer
// Tenants is the control plane, for the switcher. It is the one cross-tenant
// read in this module, and it needs the token Routes is handed.
Tenants tenantcontracts.Service
// Theme is the installation's two palettes. The zero value is the palette
// this repository ships; a client with its own colours sets this and
// changes nothing else, because every rule above the tokens is written in
// terms of a role. See design.Pair.
Theme design.Pair
// Messages and Locale opt the sign-in page into translated copy. Compose
// Messages() or an application catalog before mounting. Other pages keep
// their authored language. Locale selects a preference before the browser.
Messages page.Messages
Locale func(context.Context, page.Request) string
// Storybook selects and authorizes the composition for the resolved tenant
// and principal in ctx. Return an error to deny access; never select from a
// query parameter or fall back to another tenant. Nil exposes Core only to
// the operator tenant. Empty Examples stays empty. Every gallery endpoint
// also requires PermissionGalleryRead before calling this function.
Storybook func(context.Context) (export.Storybook, error)
}
Deps is what the shell cannot make for itself.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package internal is the shell's implementation: one chrome, one frame, the five pages written by hand, the catalog, and the screens ui/screens generates for every resource kit/rest registered before this module was composed.
|
Package internal is the shell's implementation: one chrome, one frame, the five pages written by hand, the catalog, and the screens ui/screens generates for every resource kit/rest registered before this module was composed. |