npm - staffa - Versions diffs - 0.7.3 → 0.8.0 - Mend

staffa 0.7.3 → 0.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (41) hide show

package/README.md +113 -7
package/dist/components/autocomplete.js +9 -3
package/dist/components/box.d.ts +20 -0
package/dist/components/box.js +43 -3
package/dist/components/dialog.js +17 -10
package/dist/components/layers.d.ts +330 -0
package/dist/components/layers.js +888 -0
package/dist/components/main.d.ts +98 -6
package/dist/components/main.js +222 -37
package/dist/components/menu.d.ts +14 -1
package/dist/components/menu.js +32 -4
package/dist/components/panels.d.ts +349 -0
package/dist/components/panels.js +933 -0
package/dist/components/tabs.d.ts +5 -0
package/dist/components/tabs.js +125 -19
package/dist/core.d.ts +7 -0
package/dist/core.js +7 -0
package/dist/index.d.ts +3 -2
package/dist/index.js +3 -2
package/dist/staffa.esm.js +1 -1
package/package.json +7 -5
package/skill/BoxOptions.md +18 -0
package/skill/MainOptions.md +99 -3
package/skill/Page.md +108 -0
package/skill/PathParams.md +7 -0
package/skill/SKILL.md +185 -7
package/skill/SegParams.md +8 -0
package/skill/box.md +4 -0
package/skill/isFloatingMenuOpen.md +12 -0
package/skill/main.md +14 -2
package/skill/panels.md +10 -0
package/skill/tabs.md +5 -0
package/src/components/autocomplete.ts +8 -2
package/src/components/box.ts +57 -2
package/src/components/dialog.ts +16 -10
package/src/components/main.ts +314 -40
package/src/components/menu.ts +33 -5
package/src/components/panels.ts +1167 -0
package/src/components/tabs.ts +126 -19
package/src/core.ts +8 -0
package/src/index.ts +3 -2

package/dist/components/layers.d.ts ADDED Viewed

@@ -0,0 +1,330 @@
+/**
+ * Routed, multi-column "layer stack" navigation for {@link main}.
+ *
+ * An app designs every screen ("layer") as a narrow column. On a phone exactly
+ * one layer is visible — classic push/pop stack navigation. On a wider screen as
+ * many *top-of-stack* layers as fit are shown side by side, left-to-right =
+ * shallow-to-deep. Same code, no media queries in the app.
+ *
+ * Navigation is URL-driven through `aberdeen/route`: the URL carries the *top*
+ * layer, while the layers beneath it live in the history entry's state — so the
+ * browser's back/forward buttons walk an undo history of whole stack snapshots,
+ * and a reload (or a shared link) reproduces the columns exactly.
+ */
+/** Flattens an intersection into a single object type, so hovers read nicely. */
+type Prettify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+/**
+ * The params contributed by a single path-template segment: `:x` a string,
+ * `:x(num)` a number, `*x` the remaining segments as `string[]`.
+ */
+export type SegParams<S extends string> = S extends `:${infer Name}(num)` ? {
+    [K in Name]: number;
+} : S extends `:${infer Name}` ? {
+    [K in Name]: string;
+} : S extends `*${infer Name}` ? {
+    [K in Name]: string[];
+} : {};
+/**
+ * The params object described by a path template, e.g.
+ * `PathParams<"/projects/:id/tasks/:taskId(num)">` is
+ * `{ id: string; taskId: number }`.
+ */
+export type PathParams<P extends string> = P extends `${infer Head}/${infer Rest}` ? SegParams<Head> & PathParams<Rest> : SegParams<P>;
+/** A layer draw function: it receives the layer's {@link Page} and draws into the current scope. */
+export type RouteHandler<P = any> = (page: Page<P>) => void;
+/**
+ * A route table: path templates mapped to layer draw functions. Used as the
+ * loose (non-inferred) type; `S.main()` infers a more precise type from the
+ * literal you pass, so each handler's `$page.params` is typed per its key.
+ */
+export type Routes = Record<string, RouteHandler>;
+/**
+ * The shape `S.main()`'s `routes` option is checked against: every key types its
+ * own handler's `params`. Used as a self-referential generic constraint, which
+ * is what makes `$page.params` infer from the route key.
+ */
+export type RouteTable<R> = {
+    [K in keyof R & string]: (page: Page<Prettify<PathParams<K>>>) => void;
+};
+/**
+ * The per-layer state object, an Aberdeen proxy passed to the route handler as
+ * its only argument. The handler draws inside the layer's own reactive scope, so
+ * mutating the page (a `title` arriving with the data, `loading` flipping off)
+ * updates the shell in place.
+ *
+ * Search params and the hash belong to the **top** layer only — a layer that is
+ * pushed under another one keeps only its path, so anything a layer needs to
+ * redraw itself must live in that path.
+ */
+export interface Page<P = Record<string, string | number | string[]>> {
+    /**
+     * The params matched from this layer's path, typed per its route key:
+     * `:x` is a `string`, `:x(num)` a `number`, `*x` a `string[]`. Read-only.
+     */
+    readonly params: P;
+    /** This layer's path, e.g. `"/projects/7"`. Read-only. */
+    readonly path: string;
+    /** Shown in `document.title` while this layer is top-most. */
+    title?: string;
+    /**
+     * How much room this layer asks for.
+     *
+     * - `"medium"` (the default) fills the standard content area exactly — the
+     *   room a 1280px page leaves beside the sidebar.
+     * - `"small"` is half of that content area (minus a gutter) whenever the
+     *   screen is wide enough for two columns. A lone small leaves its other
+     *   half open — which is exactly where the next pushed small lands, without
+     *   anything on screen moving. On a screen too narrow for two columns it
+     *   fills the whole content area, like a medium.
+     * - `"large"` takes as much room as the window has: while it is the visible
+     *   layer the whole shell (top bar, body, footer) stretches to the screen
+     *   edges instead of the standard 1280px page.
+     *
+     * As many top-of-stack layers as the window fits are shown side by side; on
+     * a wide enough screen the page stretches beyond its standard 1280px —
+     * staying centred — to hold them (three smalls, a medium and a small, ...).
+     *
+     * Widths depend only on the window — never on what else is open — so a
+     * layer is never resized except when the window itself is. Read **once**,
+     * right after the handler's synchronous run: set it in the handler, because
+     * later changes are ignored.
+     */
+    layout?: "small" | "medium" | "large";
+    /**
+     * Set `true` while the layer is still fetching what it needs, and back to
+     * `false` when done. A freshly pushed layer that is `loading` briefly holds
+     * its enter animation so it can slide in with real content; if the fetch
+     * drags on it slides in anyway and shows a built-in loading indicator until
+     * the flag clears. Presentation only — the stack, the URL and the close
+     * guards are never delayed by it.
+     */
+    loading?: boolean;
+    /**
+     * Close guard. Called — and awaited — whenever anything would remove this
+     * layer: Escape, this page's own close affordances ({@link Page.close}, a box
+     * with `close: true`), browser back, a link that truncates past it, or
+     * {@link layers}.`close()`. Return `false` to veto. Typical use: a dirty check
+     * plus {@link confirm}.
+     */
+    requestClose?: () => boolean | Promise<boolean>;
+    /**
+     * Guarded close of **this** layer, wherever it sits in the stack. The top
+     * layer pops (back to the snapshot beneath it); a layer that isn't on top is
+     * *spliced* out — the columns above it keep their place, their DOM and their
+     * state, and the URL doesn't change. Either way it is recorded as a history
+     * entry, so the browser's back button restores the closed column.
+     *
+     * Resolves `false` when {@link Page.requestClose} vetoed (or when the layer is
+     * the only one on the stack, and so has nothing to close back to). The shell
+     * draws no close chrome of its own, so this — or `S.box`'s `close` option — is
+     * how a page provides its way out.
+     *
+     * @example
+     * ```ts
+     * S.button({ content: "Cancel", attrs: ".neutral", click: () => void $page.close() });
+     * ```
+     */
+    close(): Promise<boolean>;
+}
+/** Options the layer stack needs from its shell. */
+export interface LayerStackOptions {
+    routes: Routes;
+    notFound?: RouteHandler<{}>;
+    /** Set `false` to show only the top layer, however much room there is. */
+    stacking?: boolean;
+    /** The shell's own title, used as the suffix of `document.title`. */
+    title?: unknown;
+}
+export declare class LayerController {
+    private compiled;
+    private opts;
+    /** The live stack, shallow-to-deep. Closing layers are no longer part of it. */
+    private live;
+    private byId;
+    private nextId;
+    /** Drives rendering: layer id → its `order` (used only as the sort key). */
+    $ids: Record<string, number>;
+    /**
+     * The live stack's paths and its top layer, for reactive readers: the
+     * `document.title` watcher, `main()`'s Escape handling and `S.layers.stack`.
+     */
+    $state: {
+        paths: string[];
+        topId: number;
+    };
+    private containerEl?;
+    /** The body width at the last layout; a change means a window resize → snap. */
+    private lastBodyW;
+    private layoutQueued;
+    private timers;
+    constructor(opts: LayerStackOptions);
+    /** Resolve a path to its route handler + params, falling back to `notFound`. */
+    private resolve;
+    private matches;
+    /**
+     * The one derivation rule for origin-less navigation (§2.8): probe every
+     * prefix of the path against the route table; the matching prefixes become
+     * the stack. Prefixes without a route are simply skipped, so an app that
+     * doesn't want one screen stacked under another just doesn't route that
+     * prefix. The path itself is always the top layer, matched or not.
+     */
+    deriveStack(path: string): string[];
+    /** The stack a route implies: its snapshot topped by its path, or — without a snapshot — derived. */
+    private targetFor;
+    /** The stack the current history entry asks for. Subscribes to path + snapshot. */
+    private computeTarget;
+    /**
+     * The route guard (see `route.setGuard` in the constructor): asked before any
+     * route change lands, wherever it came from. Runs the {@link Page.requestClose}
+     * guard of every layer the new route's stack would remove — a set defined by
+     * the target (the commit reconciles by path), so a derived stack that shares
+     * nothing with the live one still asks exactly the layers that are closing.
+     */
+    private checkChange;
+    private paths;
+    /** The live layers a target stack drops — by path, so a splice removes only its own column. */
+    private removedBy;
+    /**
+     * Adopt a stack proposed by the URL. Close guards have already been run (and
+     * have passed) by the time a route change is visible here — `checkChange` is
+     * consulted by the router itself, before anything is applied.
+     */
+    private propose;
+    /**
+     * Apply a target stack: unmount what's gone, mount what's new, animate the
+     * difference.
+     *
+     * Reconciliation is BY PATH (a stack can't hold the same path twice, so that's
+     * well-defined): a layer present in both stacks stays mounted *even if its
+     * index shifted*, which is what lets a layer be spliced out of the middle
+     * (§7) without disturbing the columns above it. A common-prefix diff would
+     * remount every one of them, throwing away exactly the scroll and form state
+     * rule 5 promises to keep.
+     */
+    private commit;
+    private createEntry;
+    /**
+     * Start a layer's exit: it lingers in the DOM, inert and fading, and is dropped
+     * only when the fade itself ends. Removing it on a fixed timer instead would
+     * race the transition — pull the element a frame early and the layer appears to
+     * fade half-way and then vanish. The timeout is just a fallback for when no
+     * `transitionend` is coming at all (transitions off, or an element that never
+     * got placed).
+     */
+    private beginClose;
+    /**
+     * Navigate back to a stack that is a truncation of the current one — the shared
+     * implementation of Escape, a page closing itself, return-links and
+     * `S.layers.close()`. `route.back()` prefers the history entry where that
+     * layer was on top (with its scroll state intact); when there is no such entry
+     * it replaces the current one, carrying the snapshot passed as the fallback.
+     * Either way the route guard asks the closing layers first, and the returned
+     * promise reports its verdict.
+     */
+    private goBackTo;
+    /** Close every layer above `index` (guarded). Resolves `false` when vetoed. */
+    closeDownTo(index: number): Promise<boolean>;
+    /** Guarded close of the top layer. */
+    closeTop(): Promise<boolean>;
+    /**
+     * Guarded close of the layer at `index`, top of the stack or not — what a
+     * page's own close affordances ({@link Page.close}, a box's ✕) come down to.
+     *
+     * The top layer pops back to the snapshot beneath it. Any other layer is
+     * *spliced* out: its guard runs, the columns above it keep their place and
+     * state (the commit reconciles by path), and the URL doesn't change, since the
+     * top layer didn't. That still gets its own history entry, so the browser's
+     * back button restores the closed column like any other snapshot — which is
+     * why it goes through `route.go` here rather than through `navigate()`, whose
+     * "link to the layer we're already on" check would see a no-op.
+     */
+    closeLayerAt(index: number): Promise<boolean>;
+    /** Guarded close of whichever layer `path` is open as. False when it isn't open. */
+    closeByPath(path: string): Promise<boolean>;
+    /** Guarded close of the layer whose `.s-layer` element this is. */
+    closeLayerEl(el: HTMLElement): Promise<boolean>;
+    /**
+     * Navigate to `href`. `originIndex` is the depth of the layer the link lives
+     * in (−1 when it has none — a nav item or a programmatic call, which derives
+     * the whole stack instead). `replace` swaps the originating layer rather than
+     * stacking on top of it.
+     */
+    navigate(href: string, originIndex: number, replace?: boolean): void;
+    /** Programmatic push/replace, with the top layer as the implied origin. */
+    pushPath(path: string, replace: boolean): void;
+    /**
+     * Link handling through `route.interceptLinks()`, whose handler hook hands us
+     * the anchor so we can decide what the click *means*: the originating
+     * `.s-layer` (which decides what the click truncates), `data-layer=replace`,
+     * and return-to-an-open-layer semantics. The exclusion rules (targets,
+     * downloads, modified clicks, external URLs) live in Aberdeen; the close
+     * guards run in `checkChange` when our navigation reaches the router.
+     */
+    private interceptLinks;
+    /** `"<page title> · <app title>"`, kept in sync with the top layer. */
+    private watchTitle;
+    /**
+     * Draw the layer viewport into the current element. Called by `main()`.
+     *
+     * There is deliberately no close chrome here — no back rail, no ←: pages
+     * provide their own way out (see {@link Page.close} and `S.box`'s `close`
+     * option). The shell contributes Escape and the browser's own back button.
+     */
+    drawStack(): void;
+    private drawLayer;
+    scheduleLayout(): void;
+    /**
+     * Size and position every layer, and publish the width of the whole ensemble
+     * (sidebar + separator + columns) for the shell to centre itself on.
+     *
+     * This is everything CSS can't work out for itself: which layers exist, which
+     * of them are visible, how wide each one is and where it sits. All the motion
+     * between two of these arrangements is CSS's job.
+     */
+    private layout;
+    /** Let a `loading` layer's enter animation wait — but not indefinitely. */
+    private holdEnter;
+}
+/**
+ * Programmatic navigation for the routed `S.main()` shell — for acts that aren't
+ * link clicks, such as pushing the screen for a record you just created.
+ *
+ * The same rules as a link click apply: pushing a path that is already an open
+ * layer *returns* to it instead of duplicating it, and anything that would
+ * remove a layer asks its {@link Page.requestClose} guard first.
+ *
+ * @example
+ * ```ts
+ * S.button({ content: "New task", click: async () => {
+ *   const task = await createTask();
+ *   S.layers.push(`/tasks/${task.id}`);
+ * }});
+ * ```
+ */
+export declare const layers: {
+    /** Push `path` on top of the current top layer. */
+    push(path: string): void;
+    /** Replace the current top layer with `path`. */
+    replace(path: string): void;
+    /**
+     * Guarded close: of the top layer, or — given a `path` — of whichever layer is
+     * open at it, which is *spliced* out when it isn't on top (the columns above it
+     * stay exactly as they are). Resolves `false` when a guard vetoed, or when
+     * `path` isn't an open layer.
+     */
+    close(path?: string): Promise<boolean>;
+    /** The current stack of paths, shallow-to-deep. Reactive: safe to read in a scope. */
+    readonly stack: readonly string[];
+};
+/**
+ * Guarded close of the layer `el` sits in, resolved from the DOM — which is what
+ * lets a close affordance work without any page context, from any column,
+ * whether or not it is on top. Used by `S.box`'s `close: true`.
+ *
+ * Outside a routed shell (or outside any layer — a box in a dialog, say) there is
+ * nothing to close: it warns and resolves `false`.
+ */
+export declare function closeContainingLayer(el: Element | null | undefined): Promise<boolean>;
+export {};