@pilotiq/pilotiq 0.1.0

package/dist/Resource.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Resource.js","sourceRoot":"","sources":["../src/Resource.ts"],"names":[],"mappings":"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"}

package/dist/RightPanel.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Right-sidebar plugin contributions.
+ *
+ * The right sidebar is a panel-level surface (mirroring `userMenuItems`
+ * / `databaseNotifications` in shape) that plugins register panes on.
+ * Pilotiq core ships the chrome — collapse toggle, drag-to-resize, tab
+ * strip when 2+ contributions, mobile sheet fallback, keyboard shortcut.
+ * Each contribution provides only its body.
+ *
+ * Wire shape (`RightPanelMeta` / `RightSidebarMeta`) lives in
+ * `pageData.ts` next to `DatabaseNotificationsMeta`. The React component
+ * reference (`render`) does not serialize over the wire — it rides
+ * through the Vite plugin's `_components.ts` manifest keyed by `id`,
+ * same posture as component-typed Resource icons.
+ *
+ * @see docs/plans/right-sidebar.md
+ */
+import type { ComponentType } from 'react';
+import type { IconValue } from './icons/types.js';
+/**
+ * Body component contract. The component receives runtime context the
+ * surrounding chrome already knows about — base path, current pathname,
+ * the active contribution id — so plugin authors don't have to plumb it
+ * separately.
+ *
+ * Plugins that need richer state (chat session, presence cache) wrap
+ * their own provider around the body internally; pilotiq doesn't
+ * prescribe one.
+ */
+export interface RightPanelProps {
+    /** Path-prefix the panel is mounted under (matches `AppShell.basePath`). */
+    basePath: string;
+    /** Live pathname — re-renders on SPA navigation so panes can react to
+     *  which page the user is on (record id, resource slug, etc). */
+    currentPath?: string;
+    /** Active contribution id (this contribution's `id` when mounted).
+     *  Useful for consumers that share a single context across multiple
+     *  registered panes. */
+    activeId: string;
+}
+export interface RightPanelContribution {
+    /** Stable id (e.g. `'ai.chat'`). Doubles as the localStorage key
+     *  segment for `activeId` and the tab strip's discriminator. Must
+     *  match `^[A-Za-z0-9_.-]+$`; uniqueness enforced at boot. */
+    id: string;
+    /** Tab strip label. Defaults to `id` when absent. */
+    label?: string;
+    /** Tab strip icon (registry name OR component). */
+    icon?: IconValue;
+    /** Body component. Pilotiq's Vite plugin keys it under `id` in the
+     *  emitted `_components.ts` manifest so the client looks it up at
+     *  mount time without shipping the component reference over the wire. */
+    render: ComponentType<RightPanelProps>;
+    /** Default open width in px. Clamped to [240, 800]; defaults to 360. */
+    defaultWidth?: number;
+    /**
+     * Optional auth gate — runs through `panelInfo()` per request. Mirrors
+     * `Resource.canAccess` shape: opaque user, sync or async, throwing →
+     * fail-closed (contribution dropped silently).
+     */
+    canAccess?: (user: unknown) => boolean | Promise<boolean>;
+    /**
+     * Hide from the tab strip without unregistering. Useful for "trigger
+     * only" panes opened programmatically by another plugin's affordance.
+     * Default `false`.
+     */
+    hidden?: boolean;
+    /** Tab strip ordering hint — lower first. Defaults to 100; ties break
+     *  by registration order. */
+    sort?: number;
+}
+/** Minimum/maximum width (px) the chrome will allow on resize. */
+export declare const RIGHT_PANEL_MIN_WIDTH = 240;
+export declare const RIGHT_PANEL_MAX_WIDTH = 800;
+export declare const RIGHT_PANEL_DEFAULT_WIDTH = 360;
+/**
+ * Validate one contribution at registration time. Catches the obvious
+ * boot-time foot-guns (bad id, missing render) so a misconfigured panel
+ * fails on `Pilotiq.make(...)` rather than on first request.
+ *
+ * @internal
+ */
+export declare function validateRightPanel(contribution: RightPanelContribution): void;
+/**
+ * Detect duplicate ids across an arrival contribution and the
+ * already-registered set. Caller throws — keeps the error message
+ * formatting in one place.
+ *
+ * @internal
+ */
+export declare function findDuplicateRightPanelId(registered: readonly RightPanelContribution[], arriving: RightPanelContribution): RightPanelContribution | undefined;
+//# sourceMappingURL=RightPanel.d.ts.map

package/dist/RightPanel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RightPanel.d.ts","sourceRoot":"","sources":["../src/RightPanel.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,OAAO,CAAA;AAC1C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAA;AAEjD;;;;;;;;;GASG;AACH,MAAM,WAAW,eAAe;IAC9B,4EAA4E;IAC5E,QAAQ,EAAE,MAAM,CAAA;IAChB;qEACiE;IACjE,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;4BAEwB;IACxB,QAAQ,EAAE,MAAM,CAAA;CACjB;AAED,MAAM,WAAW,sBAAsB;IACrC;;kEAE8D;IAC9D,EAAE,EAAE,MAAM,CAAA;IACV,qDAAqD;IACrD,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,mDAAmD;IACnD,IAAI,CAAC,EAAE,SAAS,CAAA;IAChB;;6EAEyE;IACzE,MAAM,EAAE,aAAa,CAAC,eAAe,CAAC,CAAA;IACtC,wEAAwE;IACxE,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB;;;;OAIG;IACH,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IACzD;;;;OAIG;IACH,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB;iCAC6B;IAC7B,IAAI,CAAC,EAAE,MAAM,CAAA;CACd;AAED,kEAAkE;AAClE,eAAO,MAAM,qBAAqB,MAAM,CAAA;AACxC,eAAO,MAAM,qBAAqB,MAAM,CAAA;AACxC,eAAO,MAAM,yBAAyB,MAAM,CAAA;AAI5C;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,YAAY,EAAE,sBAAsB,GAAG,IAAI,CA4B7E;AAED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CACvC,UAAU,EAAE,SAAS,sBAAsB,EAAE,EAC7C,QAAQ,EAAE,sBAAsB,GAC/B,sBAAsB,GAAG,SAAS,CAEpC"}

package/dist/RightPanel.js

@@ -0,0 +1,61 @@
+/**
+ * Right-sidebar plugin contributions.
+ *
+ * The right sidebar is a panel-level surface (mirroring `userMenuItems`
+ * / `databaseNotifications` in shape) that plugins register panes on.
+ * Pilotiq core ships the chrome — collapse toggle, drag-to-resize, tab
+ * strip when 2+ contributions, mobile sheet fallback, keyboard shortcut.
+ * Each contribution provides only its body.
+ *
+ * Wire shape (`RightPanelMeta` / `RightSidebarMeta`) lives in
+ * `pageData.ts` next to `DatabaseNotificationsMeta`. The React component
+ * reference (`render`) does not serialize over the wire — it rides
+ * through the Vite plugin's `_components.ts` manifest keyed by `id`,
+ * same posture as component-typed Resource icons.
+ *
+ * @see docs/plans/right-sidebar.md
+ */
+/** Minimum/maximum width (px) the chrome will allow on resize. */
+export const RIGHT_PANEL_MIN_WIDTH = 240;
+export const RIGHT_PANEL_MAX_WIDTH = 800;
+export const RIGHT_PANEL_DEFAULT_WIDTH = 360;
+const ID_PATTERN = /^[A-Za-z0-9_.-]+$/;
+/**
+ * Validate one contribution at registration time. Catches the obvious
+ * boot-time foot-guns (bad id, missing render) so a misconfigured panel
+ * fails on `Pilotiq.make(...)` rather than on first request.
+ *
+ * @internal
+ */
+export function validateRightPanel(contribution) {
+    if (typeof contribution.id !== 'string' || contribution.id.length === 0) {
+        throw new Error(`[Pilotiq] rightPanel: contribution is missing an id. ` +
+            `Pass \`{ id: 'my-pane', render: Component }\`.`);
+    }
+    if (!ID_PATTERN.test(contribution.id)) {
+        throw new Error(`[Pilotiq] rightPanel: id "${contribution.id}" contains characters outside ` +
+            `[A-Za-z0-9_.-]. The id rides in localStorage keys and the meta wire shape.`);
+    }
+    if (typeof contribution.render !== 'function' && typeof contribution.render !== 'object') {
+        throw new Error(`[Pilotiq] rightPanel: contribution "${contribution.id}" is missing a \`render\` ` +
+            `component. Pass a React component (function or forwardRef object).`);
+    }
+    if (contribution.defaultWidth !== undefined) {
+        const w = contribution.defaultWidth;
+        if (typeof w !== 'number' || !Number.isFinite(w) || w < RIGHT_PANEL_MIN_WIDTH || w > RIGHT_PANEL_MAX_WIDTH) {
+            throw new Error(`[Pilotiq] rightPanel: contribution "${contribution.id}" has defaultWidth=${w} ` +
+                `outside the [${RIGHT_PANEL_MIN_WIDTH}, ${RIGHT_PANEL_MAX_WIDTH}] range.`);
+        }
+    }
+}
+/**
+ * Detect duplicate ids across an arrival contribution and the
+ * already-registered set. Caller throws — keeps the error message
+ * formatting in one place.
+ *
+ * @internal
+ */
+export function findDuplicateRightPanelId(registered, arriving) {
+    return registered.find((c) => c.id === arriving.id);
+}
+//# sourceMappingURL=RightPanel.js.map

package/dist/RightPanel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RightPanel.js","sourceRoot":"","sources":["../src/RightPanel.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AA2DH,kEAAkE;AAClE,MAAM,CAAC,MAAM,qBAAqB,GAAG,GAAG,CAAA;AACxC,MAAM,CAAC,MAAM,qBAAqB,GAAG,GAAG,CAAA;AACxC,MAAM,CAAC,MAAM,yBAAyB,GAAG,GAAG,CAAA;AAE5C,MAAM,UAAU,GAAG,mBAAmB,CAAA;AAEtC;;;;;;GAMG;AACH,MAAM,UAAU,kBAAkB,CAAC,YAAoC;IACrE,IAAI,OAAO,YAAY,CAAC,EAAE,KAAK,QAAQ,IAAI,YAAY,CAAC,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxE,MAAM,IAAI,KAAK,CACb,uDAAuD;YACvD,gDAAgD,CACjD,CAAA;IACH,CAAC;IACD,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,YAAY,CAAC,EAAE,CAAC,EAAE,CAAC;QACtC,MAAM,IAAI,KAAK,CACb,6BAA6B,YAAY,CAAC,EAAE,gCAAgC;YAC5E,4EAA4E,CAC7E,CAAA;IACH,CAAC;IACD,IAAI,OAAO,YAAY,CAAC,MAAM,KAAK,UAAU,IAAI,OAAO,YAAY,CAAC,MAAM,KAAK,QAAQ,EAAE,CAAC;QACzF,MAAM,IAAI,KAAK,CACb,uCAAuC,YAAY,CAAC,EAAE,4BAA4B;YAClF,oEAAoE,CACrE,CAAA;IACH,CAAC;IACD,IAAI,YAAY,CAAC,YAAY,KAAK,SAAS,EAAE,CAAC;QAC5C,MAAM,CAAC,GAAG,YAAY,CAAC,YAAY,CAAA;QACnC,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,qBAAqB,IAAI,CAAC,GAAG,qBAAqB,EAAE,CAAC;YAC3G,MAAM,IAAI,KAAK,CACb,uCAAuC,YAAY,CAAC,EAAE,sBAAsB,CAAC,GAAG;gBAChF,gBAAgB,qBAAqB,KAAK,qBAAqB,UAAU,CAC1E,CAAA;QACH,CAAC;IACH,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,yBAAyB,CACvC,UAA6C,EAC7C,QAAgC;IAEhC,OAAO,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,QAAQ,CAAC,EAAE,CAAC,CAAA;AACrD,CAAC"}

package/dist/Tab.d.ts

@@ -0,0 +1,92 @@
+import { Element, type ElementMeta } from './schema/Element.js';
+import type { ModelQuery } from './orm/modelDefaults.js';
+import type { TableContext } from './elements/Table.js';
+/** Color preset for the tab's count badge. Maps to the same palette as
+ * `BadgeColumn` so a "Drafts (5)" badge can be tinted warning/destructive
+ * etc. without inventing a new color system. */
+export type TabBadgeColor = 'default' | 'primary' | 'success' | 'warning' | 'destructive' | 'info';
+/** Server-side counter callback. Resolved in parallel during the page-data
+ * pass (see `pageData.resourceIndexData`). Returns `undefined` to omit the
+ * badge for this render — handy for "show count only when non-zero". */
+export type TabBadgeHandler = () => string | number | undefined | Promise<string | number | undefined>;
+/** ORM query customizer. Same shape as `Filter.query()` so tab predicates
+ * compose into the same `ModelQuery` chain inside `modelTableRecords`. */
+export type TabQueryHandler = (query: ModelQuery) => ModelQuery;
+/** TableContext customizer for resources that don't use the model adapter.
+ * Applied to the context before user-supplied `Table.records(fn)` runs. */
+export type TabContextHandler = (ctx: TableContext) => TableContext;
+/** Serialized shape — what the renderer reads. */
+export interface ListTabMeta extends ElementMeta {
+    type: 'listTab';
+    name: string;
+    label: string;
+    icon?: string;
+    badge?: string;
+    badgeColor?: TabBadgeColor;
+    /** True when this tab matches the URL's `?tab=` query (or is the default
+     * when the param is absent). The renderer uses this to mark the trigger
+     * with `data-active`. */
+    active: boolean;
+    /** Pre-built URL for this tab — already includes `?tab=name` plus any
+     * other carry-forward query params (search/sort/filters). The renderer
+     * uses this directly so the tab strip is just `<a href>` triggers. */
+    url: string;
+}
+/**
+ * Single list-page tab — a query-shortcut + count-badge primitive that
+ * sits in a `ListTabs` strip above the table on a resource list page.
+ * Distinct from the form-side `Tab` (under `Tabs.make().tabs([…])`) which
+ * holds form-children rather than narrowing a query.
+ *
+ * @example
+ * ListTab.make('drafts')
+ *   .label('Drafts')
+ *   .badge(() => prisma.article.count({ where: { status: 'draft' } }))
+ *   .badgeColor('warning')
+ *   .modifyQuery(q => q.where('status', 'draft'))
+ */
+export declare class ListTab extends Element {
+    readonly name: string;
+    protected _label?: string;
+    protected _icon?: string;
+    protected _badge?: string | TabBadgeHandler;
+    protected _badgeColor?: TabBadgeColor;
+    protected _default: boolean;
+    protected _queryFn?: TabQueryHandler;
+    protected _contextFn?: TabContextHandler;
+    protected _active: boolean;
+    protected _resolvedBadge?: string;
+    protected _url?: string;
+    protected constructor(name: string);
+    static make(name: string): ListTab;
+    label(l: string): this;
+    icon(i: string): this;
+    /** Static string OR server-side callback (`() => Promise<string|number>`).
+     * Callbacks resolve in parallel with the table's `records()` handler. */
+    badge(b: string | TabBadgeHandler): this;
+    badgeColor(c: TabBadgeColor): this;
+    /** Mark this tab as the default (when `?tab=` is absent). Without this
+     * flag, the first tab in `getTabs()` is the default. */
+    default(): this;
+    /** ORM query customizer — chained into `modelTableRecords` next to
+     * `Filter.query()`. Receives the running `ModelQuery` and returns the
+     * modified query (e.g. `q => q.where('status', 'draft')`). */
+    modifyQuery(fn: TabQueryHandler): this;
+    /** TableContext customizer — escape hatch for resources whose
+     * `Table.records(fn)` reads a custom field off `ctx`. Most users want
+     * `modifyQuery`. */
+    modifyContext(fn: TabContextHandler): this;
+    withActive(v?: boolean): this;
+    withResolvedBadge(s: string | undefined): this;
+    withUrl(s: string): this;
+    getLabel(): string;
+    isDefault(): boolean;
+    isActive(): boolean;
+    getBadgeHandler(): TabBadgeHandler | undefined;
+    getStaticBadge(): string | undefined;
+    getQuery(): TabQueryHandler | undefined;
+    getContextFn(): TabContextHandler | undefined;
+    getType(): string;
+    toMeta(): ListTabMeta;
+}
+//# sourceMappingURL=Tab.d.ts.map

package/dist/Tab.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Tab.d.ts","sourceRoot":"","sources":["../src/Tab.ts"],"names":[],"mappings":"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"}

package/dist/Tab.js

@@ -0,0 +1,93 @@
+import { Element } from './schema/Element.js';
+/**
+ * Single list-page tab — a query-shortcut + count-badge primitive that
+ * sits in a `ListTabs` strip above the table on a resource list page.
+ * Distinct from the form-side `Tab` (under `Tabs.make().tabs([…])`) which
+ * holds form-children rather than narrowing a query.
+ *
+ * @example
+ * ListTab.make('drafts')
+ *   .label('Drafts')
+ *   .badge(() => prisma.article.count({ where: { status: 'draft' } }))
+ *   .badgeColor('warning')
+ *   .modifyQuery(q => q.where('status', 'draft'))
+ */
+export class ListTab extends Element {
+    name;
+    _label;
+    _icon;
+    _badge;
+    _badgeColor;
+    _default = false;
+    _queryFn;
+    _contextFn;
+    // Render-time state — populated by the framework before serialization.
+    _active = false;
+    _resolvedBadge;
+    _url;
+    constructor(name) {
+        super();
+        this.name = name;
+    }
+    static make(name) {
+        return new ListTab(name);
+    }
+    // ─── Builder ──────────────────────────────────────────
+    label(l) { this._label = l; return this; }
+    icon(i) { this._icon = i; return this; }
+    /** Static string OR server-side callback (`() => Promise<string|number>`).
+     * Callbacks resolve in parallel with the table's `records()` handler. */
+    badge(b) { this._badge = b; return this; }
+    badgeColor(c) { this._badgeColor = c; return this; }
+    /** Mark this tab as the default (when `?tab=` is absent). Without this
+     * flag, the first tab in `getTabs()` is the default. */
+    default() { this._default = true; return this; }
+    /** ORM query customizer — chained into `modelTableRecords` next to
+     * `Filter.query()`. Receives the running `ModelQuery` and returns the
+     * modified query (e.g. `q => q.where('status', 'draft')`). */
+    modifyQuery(fn) { this._queryFn = fn; return this; }
+    /** TableContext customizer — escape hatch for resources whose
+     * `Table.records(fn)` reads a custom field off `ctx`. Most users want
+     * `modifyQuery`. */
+    modifyContext(fn) { this._contextFn = fn; return this; }
+    // ─── Render-time setters ─────────────────────────────
+    withActive(v = true) { this._active = v; return this; }
+    withResolvedBadge(s) {
+        if (s === undefined)
+            delete this._resolvedBadge;
+        else
+            this._resolvedBadge = s;
+        return this;
+    }
+    withUrl(s) { this._url = s; return this; }
+    // ─── Getters ─────────────────────────────────────────
+    getLabel() {
+        return this._label ?? this.name.charAt(0).toUpperCase() + this.name.slice(1);
+    }
+    isDefault() { return this._default; }
+    isActive() { return this._active; }
+    getBadgeHandler() {
+        return typeof this._badge === 'function' ? this._badge : undefined;
+    }
+    getStaticBadge() {
+        return typeof this._badge === 'string' ? this._badge : undefined;
+    }
+    getQuery() { return this._queryFn; }
+    getContextFn() { return this._contextFn; }
+    // ─── Element contract ────────────────────────────────
+    getType() { return 'listTab'; }
+    toMeta() {
+        const badge = this._resolvedBadge ?? this.getStaticBadge();
+        return {
+            type: 'listTab',
+            name: this.name,
+            label: this.getLabel(),
+            active: this._active,
+            url: this._url ?? `?tab=${encodeURIComponent(this.name)}`,
+            ...(this._icon !== undefined ? { icon: this._icon } : {}),
+            ...(badge !== undefined ? { badge } : {}),
+            ...(this._badgeColor !== undefined ? { badgeColor: this._badgeColor } : {}),
+        };
+    }
+}
+//# sourceMappingURL=Tab.js.map

package/dist/Tab.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Tab.js","sourceRoot":"","sources":["../src/Tab.ts"],"names":[],"mappings":"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"}

package/dist/UserMenuItem.d.ts

@@ -0,0 +1,76 @@
+/**
+ * UserMenuItem — a single entry in the panel's top-right user dropdown
+ * (the avatar/name menu rendered by `<UserMenu />`). Authored with
+ * `Pilotiq.userMenuItems([UserMenuItem.make('profile').label('Profile')…])`.
+ *
+ * Distinct from a `NavItem` (sidebar/topbar nav) and from an `Action`
+ * (form submits, modal handlers): a UserMenuItem is purely a labelled
+ * link with optional visibility gating. Sign-out lives separately on
+ * `Pilotiq.signOut(url)` because it needs a POST form, not an `<a href>`.
+ *
+ *   UserMenuItem.make('profile')
+ *     .label('My profile')
+ *     .icon('user')
+ *     .url('/profile')
+ *
+ *   UserMenuItem.make('docs')
+ *     .label(({ user }) => `Hi ${(user as any)?.name ?? 'there'}`)
+ *     .url('https://docs.example.com')
+ *     .openUrlInNewTab()
+ *
+ * Visibility rules mirror `Action.visible(...)` — boolean or
+ * `(ctx) => boolean | Promise<boolean>` over `{ user }`. Throwing rules
+ * fail closed (item hidden), matching the resource/global `canAccess`
+ * posture.
+ */
+import type { ActionVisibilityContext, VisibilityRule } from './actions/Action.js';
+import type { SerializedIcon } from './icons/types.js';
+export type UserMenuItemColor = 'default' | 'destructive';
+/** Static string OR a callback that builds the value off the resolved
+ *  user. Callbacks receive `{ user }` (other ctx fields stay undefined
+ *  for parity with `Action.visible`). Async return is supported. */
+export type UserMenuItemValue<T> = T | ((ctx: ActionVisibilityContext) => T | Promise<T>);
+/** Wire shape consumed by `<UserMenu />`. Items resolve to this in
+ *  `panelInfo()` (visibility gate already applied — only visible items
+ *  reach the renderer). `icon` accepts the same `SerializedIcon` shape
+ *  as nav items so the auto-injected profile entry can ride the
+ *  Page's component icon through the build-time `_components.ts`
+ *  manifest. User-authored entries via `UserMenuItem.icon('user')`
+ *  ship as plain strings (registry keys). */
+export interface UserMenuItemMeta {
+    name: string;
+    label: string;
+    icon?: SerializedIcon;
+    url?: string;
+    color?: UserMenuItemColor;
+    openInNewTab?: boolean;
+}
+export declare class UserMenuItem {
+    readonly name: string;
+    protected _label?: UserMenuItemValue<string>;
+    protected _icon?: string;
+    protected _url?: UserMenuItemValue<string>;
+    protected _color?: UserMenuItemColor;
+    protected _sort?: number;
+    protected _visible?: VisibilityRule;
+    protected _openInNewTab: boolean;
+    protected constructor(name: string);
+    static make(name: string): UserMenuItem;
+    label(l: UserMenuItemValue<string>): this;
+    icon(i: string): this;
+    url(u: UserMenuItemValue<string>): this;
+    color(c: UserMenuItemColor): this;
+    sort(n: number): this;
+    /** Boolean or `({ user }) => bool | Promise<bool>`. Throws → hidden. */
+    visible(rule: VisibilityRule): this;
+    /** Render the link with `target="_blank" rel="noopener noreferrer"`. */
+    openUrlInNewTab(v?: boolean): this;
+    getSort(): number | undefined;
+    /** Resolve the item against the current context. Returns `null` when
+     *  the visibility predicate denies (or throws). Otherwise returns the
+     *  serialized meta. The default label is derived from `name` so a
+     *  bare `UserMenuItem.make('profile')` still renders a sensible
+     *  "Profile" entry. */
+    resolve(ctx: ActionVisibilityContext): Promise<UserMenuItemMeta | null>;
+}
+//# sourceMappingURL=UserMenuItem.d.ts.map

package/dist/UserMenuItem.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"UserMenuItem.d.ts","sourceRoot":"","sources":["../src/UserMenuItem.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,OAAO,KAAK,EAAE,uBAAuB,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA;AAClF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAA;AAEtD,MAAM,MAAM,iBAAiB,GAAG,SAAS,GAAG,aAAa,CAAA;AAEzD;;oEAEoE;AACpE,MAAM,MAAM,iBAAiB,CAAC,CAAC,IAC3B,CAAC,GACD,CAAC,CAAC,GAAG,EAAE,uBAAuB,KAAK,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC,CAAA;AAEtD;;;;;;6CAM6C;AAC7C,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAa,MAAM,CAAA;IACvB,KAAK,EAAY,MAAM,CAAA;IACvB,IAAI,CAAC,EAAY,cAAc,CAAA;IAC/B,GAAG,CAAC,EAAa,MAAM,CAAA;IACvB,KAAK,CAAC,EAAW,iBAAiB,CAAA;IAClC,YAAY,CAAC,EAAI,OAAO,CAAA;CACzB;AAED,qBAAa,YAAY;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IAErB,SAAS,CAAC,MAAM,CAAC,EAAW,iBAAiB,CAAC,MAAM,CAAC,CAAA;IACrD,SAAS,CAAC,KAAK,CAAC,EAAY,MAAM,CAAA;IAClC,SAAS,CAAC,IAAI,CAAC,EAAa,iBAAiB,CAAC,MAAM,CAAC,CAAA;IACrD,SAAS,CAAC,MAAM,CAAC,EAAW,iBAAiB,CAAA;IAC7C,SAAS,CAAC,KAAK,CAAC,EAAY,MAAM,CAAA;IAClC,SAAS,CAAC,QAAQ,CAAC,EAAS,cAAc,CAAA;IAC1C,SAAS,CAAC,aAAa,UAAY;IAEnC,SAAS,aAAa,IAAI,EAAE,MAAM;IAIlC,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY;IAMvC,KAAK,CAAC,CAAC,EAAE,iBAAiB,CAAC,MAAM,CAAC,GAAG,IAAI;IACzC,IAAI,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI;IACrB,GAAG,CAAC,CAAC,EAAE,iBAAiB,CAAC,MAAM,CAAC,GAAG,IAAI;IACvC,KAAK,CAAC,CAAC,EAAE,iBAAiB,GAAG,IAAI;IACjC,IAAI,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI;IACrB,wEAAwE;IACxE,OAAO,CAAC,IAAI,EAAE,cAAc,GAAG,IAAI;IACnC,wEAAwE;IACxE,eAAe,CAAC,CAAC,UAAO,GAAG,IAAI;IAI/B,OAAO,IAAI,MAAM,GAAG,SAAS;IAE7B;;;;2BAIuB;IACjB,OAAO,CAAC,GAAG,EAAE,uBAAuB,GAAG,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC;CA0B9E"}

package/dist/UserMenuItem.js

@@ -0,0 +1,87 @@
+export class UserMenuItem {
+    name;
+    _label;
+    _icon;
+    _url;
+    _color;
+    _sort;
+    _visible;
+    _openInNewTab = false;
+    constructor(name) {
+        this.name = name;
+    }
+    static make(name) {
+        return new UserMenuItem(name);
+    }
+    // ─── Builder ──────────────────────────────────────────
+    label(l) { this._label = l; return this; }
+    icon(i) { this._icon = i; return this; }
+    url(u) { this._url = u; return this; }
+    color(c) { this._color = c; return this; }
+    sort(n) { this._sort = n; return this; }
+    /** Boolean or `({ user }) => bool | Promise<bool>`. Throws → hidden. */
+    visible(rule) { this._visible = rule; return this; }
+    /** Render the link with `target="_blank" rel="noopener noreferrer"`. */
+    openUrlInNewTab(v = true) { this._openInNewTab = v; return this; }
+    // ─── Getters ─────────────────────────────────────────
+    getSort() { return this._sort; }
+    /** Resolve the item against the current context. Returns `null` when
+     *  the visibility predicate denies (or throws). Otherwise returns the
+     *  serialized meta. The default label is derived from `name` so a
+     *  bare `UserMenuItem.make('profile')` still renders a sensible
+     *  "Profile" entry. */
+    async resolve(ctx) {
+        let visible = true;
+        if (this._visible !== undefined) {
+            try {
+                visible = typeof this._visible === 'function'
+                    ? Boolean(await this._visible(ctx))
+                    : Boolean(this._visible);
+            }
+            catch {
+                visible = false;
+            }
+        }
+        if (!visible)
+            return null;
+        const label = await resolveValue(this._label, ctx) ?? defaultLabel(this.name);
+        const url = await resolveValue(this._url, ctx);
+        const meta = {
+            name: this.name,
+            label,
+        };
+        if (this._icon !== undefined)
+            meta.icon = this._icon;
+        if (url !== undefined)
+            meta.url = url;
+        if (this._color !== undefined)
+            meta.color = this._color;
+        if (this._openInNewTab)
+            meta.openInNewTab = true;
+        return meta;
+    }
+}
+async function resolveValue(raw, ctx) {
+    if (raw === undefined)
+        return undefined;
+    if (typeof raw === 'function') {
+        try {
+            return await raw(ctx);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    return raw;
+}
+function defaultLabel(name) {
+    if (!name)
+        return '';
+    // Camel/kebab/snake → "Title Case" (cheap; users override via `.label()`)
+    const spaced = name
+        .replace(/[-_]+/g, ' ')
+        .replace(/([a-z])([A-Z])/g, '$1 $2')
+        .toLowerCase();
+    return spaced.charAt(0).toUpperCase() + spaced.slice(1);
+}
+//# sourceMappingURL=UserMenuItem.js.map

package/dist/UserMenuItem.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"UserMenuItem.js","sourceRoot":"","sources":["../src/UserMenuItem.ts"],"names":[],"mappings":"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"}