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

staffa 0.7.4 → 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 (37) hide show

package/README.md +113 -7
package/dist/components/box.d.ts +20 -0
package/dist/components/box.js +43 -3
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 +2 -1
package/dist/index.js +2 -1
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 +173 -9
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/box.ts +57 -2
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 +2 -1

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

@@ -0,0 +1,349 @@
+/**
+ * Routed, multi-column panel navigation for {@link main}.
+ *
+ * Each route draws one screen of the app, called a panel, and as many panels as
+ * fit are shown at a time. On a phone that is one, so a link opens a new panel
+ * on top and closing it brings the previous one back. On a wider screen the
+ * panels that would have covered each other sit side by side instead, oldest on
+ * the left. The app's own code is the same either way.
+ *
+ * Navigation runs through `aberdeen/route`: the URL holds the top panel, and
+ * the ones beneath it are stored beside it in the history entry. So back and
+ * forward step through whole arrangements of columns, and a reload (or a shared
+ * link) brings the same columns back.
+ */
+/** Flattens an intersection into a single object type, so hovers read nicely. */
+type Prettify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+/**
+ * What a `[name=matcher]` matcher name yields. An unrecognised name resolves to
+ * `never`, which shows up as an unusable param at the handler rather than
+ * quietly typing as `string` (the route key itself throws at mount time).
+ */
+export type MatcherType<M extends string> = M extends "integer" ? number : never;
+/**
+ * The params contributed by a single path-template segment: `[x]` a string,
+ * `[x=integer]` a number, `[...x]` the rest of the path as one raw string.
+ */
+export type SegParams<S extends string> = S extends `[...${infer Name}]` ? {
+    [K in Name]: string;
+} : S extends `[${infer Name}=${infer Matcher}]` ? {
+    [K in Name]: MatcherType<Matcher>;
+} : S extends `[${infer Name}]` ? {
+    [K in Name]: string;
+} : {};
+/**
+ * The params object described by a path template, e.g.
+ * `PathParams<"/projects/[id]/tasks/[taskId=integer]">` is
+ * `{ id: string; taskId: number }`.
+ */
+export type PathParams<P extends string> = P extends `${infer Head}/${infer Rest}` ? SegParams<Head> & PathParams<Rest> : SegParams<P>;
+/** A panel draw function: it receives the panel'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 panel 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;
+};
+/**
+ * What a route handler gets: the params from its route, plus everything the
+ * shell needs to know about the panel it is drawing. It's an Aberdeen proxy, so
+ * you can set things later, such as a `title` that arrives with your data or
+ * `loading` going back to `false`, and the shell keeps up.
+ *
+ * Search params and the `#hash` belong to the top panel only. A panel with
+ * another one on top of it keeps just its path, so anything a panel needs in
+ * order to redraw itself has to live in that path.
+ */
+export interface Page<P = Record<string, string | number | string[]>> {
+    /**
+     * The params matched from this panel's path, typed per its route key:
+     * `[x]` is a `string`, `[x=integer]` a `number`, `[...x]` a `string`.
+     * Read-only.
+     */
+    readonly params: P;
+    /** This panel's path, e.g. `"/projects/7"`. Read-only. */
+    readonly path: string;
+    /** Shown in `document.title` while this panel is top-most. */
+    title?: string;
+    /**
+     * How much room this panel takes. The content area is the page, at most
+     * 1280px wide, minus the nav sidebar; the widths below assume a sidebar of
+     * around 170px, so without one add that back.
+     *
+     * - `"small"` is 360 to 540px once two panels fit side by side, which is
+     *   what makes it right for lists, detail forms, and anything else that
+     *   reads well at phone width. Below that it takes the whole content area
+     *   (so up to ~730px), like a medium does. A lone small leaves its other
+     *   half empty, and that is exactly where the next small lands, without
+     *   anything on screen moving.
+     * - `"medium"` (the default) takes the whole content area: up to ~1100px,
+     *   and the screen width on a phone. The safe default for ordinary screens.
+     *   Nothing fits beside a medium on a standard 1280px page, though on a wide
+     *   enough window a small still can.
+     * - `"large"` takes the whole window, with no upper limit (~1750px on a
+     *   1920px screen): for boards, wide tables and dense dashboards. While it's
+     *   open the whole shell (top bar, content and footer) stretches to the
+     *   screen edges rather than stopping at 1280px.
+     *
+     * When more columns fit than the standard page holds (three smalls, or a
+     * medium and a small) the page itself grows, staying centred, to hold them.
+     *
+     * A panel's width depends only on the size of the window, never on what else
+     * is open, so opening or closing a panel never resizes the ones already on
+     * screen. This is read **once**, right after your handler runs, so set it
+     * there; later changes are ignored.
+     */
+    layout?: "small" | "medium" | "large";
+    /**
+     * Set this while you're fetching what the panel needs, and back to `false`
+     * when you're done. A new panel waits a moment before sliding in, so it can
+     * arrive with real content instead of empty; if the wait drags on it slides
+     * in anyway and shows a loading indicator until the flag clears. It only
+     * affects the animation; the stack, the URL and `requestClose` never wait
+     * for it.
+     */
+    loading?: boolean;
+    /**
+     * Your chance to say no. Everything that would close this panel waits for
+     * it: Escape, the panel's own ✕ or Cancel button ({@link Page.close}, or a
+     * box with `close: true`), the browser's back button, a link that would
+     * close it, and {@link panels}.`close()`. Return `false` to keep the panel
+     * open, usually after a dirty check and a {@link confirm}.
+     */
+    requestClose?: () => boolean | Promise<boolean>;
+    /**
+     * Closes **this** panel, wherever it sits in the stack. The top panel goes
+     * back to whatever was underneath it; any other panel is taken out on its
+     * own, leaving the columns to its right where they are, with their state,
+     * and the URL alone, since the top panel didn't move. Either way it
+     * becomes a history entry, so the browser's back button brings it back.
+     *
+     * Resolves `false` if the panel didn't close: {@link Page.requestClose} said
+     * no, it was the only panel on the stack (so there's nothing to go back to),
+     * or another navigation got there first. The shell draws no back arrows or
+     * ✕ of its own, so this (or `S.box`'s `close` option) is how a panel gives
+     * the user a way out.
+     *
+     * @example
+     * ```ts
+     * S.button({ content: "Cancel", attrs: ".neutral", click: () => void $page.close() });
+     * ```
+     */
+    close(): Promise<boolean>;
+}
+/** Options the panel stack needs from its shell. */
+export interface PanelStackOptions {
+    routes: Routes;
+    notFound?: RouteHandler<{}>;
+    /** Set `false` to show only the top panel, however much room there is. */
+    stacking?: boolean;
+    /** The shell's own title, used as the suffix of `document.title`. */
+    title?: unknown;
+}
+export declare class PanelController {
+    private compiled;
+    private opts;
+    /** The live stack, shallow-to-deep. Closing panels are no longer part of it. */
+    private live;
+    private byId;
+    private nextId;
+    /** Drives rendering: panel id → its `order` (used only as the sort key). */
+    $ids: Record<string, number>;
+    /**
+     * The live stack's paths and its top panel, for reactive readers: the
+     * `document.title` watcher, `main()`'s Escape handling and `S.panels.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: PanelStackOptions);
+    /** 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 panel, 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 panel 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 panels that are closing.
+     */
+    private checkChange;
+    private paths;
+    /** The live panels 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 panel present in both stacks stays mounted *even if its
+     * index shifted*, which is what lets a panel 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 panel'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 panel 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.panels.close()`. `route.back()` prefers the history entry where that
+     * panel 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 panels first, and the returned
+     * promise reports its verdict.
+     */
+    private goBackTo;
+    /** Close every panel above `index` (guarded). Resolves `false` when vetoed. */
+    closeDownTo(index: number): Promise<boolean>;
+    /** Guarded close of the top panel. */
+    closeTop(): Promise<boolean>;
+    /**
+     * Guarded close of the panel 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 panel pops back to the snapshot beneath it. Any other panel 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 panel 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 panel we're already on" check would see a no-op.
+     */
+    closePanelAt(index: number): Promise<boolean>;
+    /** Guarded close of whichever panel `path` is open as. False when it isn't open. */
+    closeByPath(path: string): Promise<boolean>;
+    /** Guarded close of the panel whose `.s-panel` element this is. */
+    closePanelEl(el: HTMLElement): Promise<boolean>;
+    /**
+     * Navigate to `href`. `originIndex` is the depth of the panel 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 panel rather than
+     * stacking on top of it.
+     */
+    navigate(href: string, originIndex: number, replace?: boolean): void;
+    /** Programmatic push/replace, with the top panel 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-panel` (which decides what the click truncates), `data-panel=replace`,
+     * and return-to-an-open-panel 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 panel. */
+    private watchTitle;
+    /**
+     * Draw the panel 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 drawPanel;
+    scheduleLayout(): void;
+    /**
+     * Size and position every panel, 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 panels 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` panel's enter animation wait — but not indefinitely. */
+    private holdEnter;
+}
+/**
+ * Navigating the routed `S.main()` shell from code, for the times it isn't a
+ * link click, such as opening the screen for a record you just created.
+ *
+ * The same rules as a link click apply: pushing a path that is already open
+ * goes back to it rather than opening it twice, and anything that would close a
+ * panel asks its {@link Page.requestClose} first.
+ *
+ * @example
+ * ```ts
+ * S.button({ content: "New task", click: async () => {
+ *   const task = await createTask();
+ *   S.panels.push(`/tasks/${task.id}`);
+ * }});
+ * ```
+ */
+export declare const panels: {
+    /** Opens `path` in a new panel on top of the top one. */
+    push(path: string): void;
+    /**
+     * Opens `path` in place of the top panel, which closes (asking its
+     * {@link Page.requestClose} first). The panels beneath it stay as they are.
+     */
+    replace(path: string): void;
+    /**
+     * Closes the top panel, or, given a `path`, whichever panel is open at it,
+     * asking {@link Page.requestClose} first. A panel that isn't on top is taken
+     * out on its own, leaving the columns to its right exactly as they are.
+     *
+     * Resolves `false` if the panel didn't close: `requestClose` said no, `path`
+     * isn't open, or another navigation got there first.
+     */
+    close(path?: string): Promise<boolean>;
+    /** The paths of the open panels, oldest first. Reactive: safe to read in a scope. */
+    readonly stack: readonly string[];
+};
+/**
+ * Closes the panel `el` sits in, working out which one that is from the DOM.
+ * That is what lets a close button work without being handed a `$page`, from
+ * any column, whether or not it is on top. Used by `S.box`'s `close: true`.
+ *
+ * Outside a routed shell (or outside any panel, such as a box in a dialog) there is
+ * nothing to close: it warns and resolves `false`.
+ */
+export declare function closeContainingPanel(el: Element | null | undefined): Promise<boolean>;
+export {};