@peasant-labs/fairtrade 0.0.30 → 0.0.32

package/dist/lib/types/AppSidebar.d.ts

@@ -0,0 +1,215 @@
+/**
+ * The shared app sidebar: brand, collapse toggle, the caller's nav groups, the online / local /
+ * docs app switcher and an account row. A sticky resizable column on desktop that collapses to an
+ * icon rail; a top bar plus an opaque drawer below 768px.
+ * @param {AppSidebarProps} props
+ */
+export default function AppSidebar({ app, apps, groups, currentId, homeHref, brand, account, accountSlot, LinkComponent, storageKey, defaultCollapsed, defaultWidth, minWidth, maxWidth, onCollapsedChange, label, className, }: AppSidebarProps): import("react").JSX.Element;
+/**
+ * The page frame for an app screen: the sidebar column beside a main column that takes the rest
+ * (min-width 0, so wide content stays contained). One column below 768px, the top bar above the page.
+ * @param {AppSidebarLayoutProps} props
+ */
+export function AppSidebarLayout({ sidebar, children, className }: AppSidebarLayoutProps): import("react").JSX.Element;
+/**
+ * @typedef {Object} AppSidebarApp
+ * @property {string} id         'online' | 'local' | 'docs', or another app id (shown with a generic icon).
+ * @property {string} label      the switcher label.
+ * @property {string} [href]     where the app lives. A non-current app without an href is omitted.
+ * @property {string} [target]
+ * @property {string} [rel]
+ */
+/**
+ * @typedef {Object} AppSidebarItem
+ * @property {string} id
+ * @property {string} label                rendered as given (never lowercased: it may be user content).
+ * @property {string} [href]               renders a link (or `LinkComponent`).
+ * @property {(id: string) => void} [onSelect]  with no href, renders a button that calls this.
+ * @property {import('react').ComponentType<any>} [icon]  a lucide icon component.
+ * @property {string} [swatch]             a CSS colour for a 12px square in place of an icon, e.g. 'var(--olive)'.
+ * @property {boolean} [external]          the item leaves this app: a trailing marker and a spoken suffix.
+ * @property {string} [title]              tooltip; defaults to the label.
+ * @property {0|1} [depth]                 1 indents the item under the one above it.
+ * @property {string} [target]
+ * @property {string} [rel]
+ */
+/**
+ * @typedef {Object} AppSidebarGroup
+ * @property {string} id
+ * @property {string} [label]       a visible group label, shown only while expanded.
+ * @property {string} [ariaLabel]   the nav landmark name; defaults to the label, then the id.
+ * @property {AppSidebarItem[]} items
+ */
+/**
+ * @typedef {Object} AppSidebarAccount
+ * @property {string} handle   shown as @handle; its first letter fills the square avatar.
+ * @property {string} [href]   makes the account row a link.
+ */
+/**
+ * @typedef {Object} AppSidebarProps
+ * @property {'online'|'local'|'docs'|string} app   which app renders the sidebar; marks its switcher entry current.
+ * @property {AppSidebarApp[]} [apps]               the app switcher entries (default APP_SIDEBAR_APPS, no hrefs).
+ * @property {AppSidebarGroup[]} groups
+ * @property {string} [currentId]                   the id of the current item (aria-current="page").
+ * @property {string} [homeHref]                    the brand links here.
+ * @property {string} [brand]                       the wordmark, default 'peasant'.
+ * @property {AppSidebarAccount} [account]
+ * @property {import('react').ReactNode} [accountSlot]  replaces the default account row content.
+ * @property {import('react').ComponentType<any>} [LinkComponent]  a router link; receives href, className,
+ *   aria-current, title, target, rel, onClick and children.
+ * @property {string|null} [storageKey]             localStorage key prefix, default 'fairtrade.app-sidebar'; null disables persistence.
+ * @property {boolean} [defaultCollapsed]
+ * @property {number} [defaultWidth]                px, default 248.
+ * @property {number} [minWidth]                    px, default 200.
+ * @property {number} [maxWidth]                    px, default 360.
+ * @property {(collapsed: boolean) => void} [onCollapsedChange]
+ * @property {string} [label]                       the aside's accessible name, default 'peasant'.
+ * @property {string} [className]
+ */
+/**
+ * @typedef {Object} AppSidebarLayoutProps
+ * @property {import('react').ReactNode} sidebar   an <AppSidebar>.
+ * @property {import('react').ReactNode} children  the page body.
+ * @property {string} [className]
+ */
+/** The app switcher's default entries, in order. Consumers map their hrefs in.
+ * @type {ReadonlyArray<Readonly<AppSidebarApp>>} */
+export const APP_SIDEBAR_APPS: ReadonlyArray<Readonly<AppSidebarApp>>;
+export type AppSidebarApp = {
+    /**
+     * 'online' | 'local' | 'docs', or another app id (shown with a generic icon).
+     */
+    id: string;
+    /**
+     * the switcher label.
+     */
+    label: string;
+    /**
+     * where the app lives. A non-current app without an href is omitted.
+     */
+    href?: string;
+    target?: string;
+    rel?: string;
+};
+export type AppSidebarItem = {
+    id: string;
+    /**
+     * rendered as given (never lowercased: it may be user content).
+     */
+    label: string;
+    /**
+     * renders a link (or `LinkComponent`).
+     */
+    href?: string;
+    /**
+     * with no href, renders a button that calls this.
+     */
+    onSelect?: (id: string) => void;
+    /**
+     * a lucide icon component.
+     */
+    icon?: import("react").ComponentType<any>;
+    /**
+     * a CSS colour for a 12px square in place of an icon, e.g. 'var(--olive)'.
+     */
+    swatch?: string;
+    /**
+     * the item leaves this app: a trailing marker and a spoken suffix.
+     */
+    external?: boolean;
+    /**
+     * tooltip; defaults to the label.
+     */
+    title?: string;
+    /**
+     * 1 indents the item under the one above it.
+     */
+    depth?: 0 | 1;
+    target?: string;
+    rel?: string;
+};
+export type AppSidebarGroup = {
+    id: string;
+    /**
+     * a visible group label, shown only while expanded.
+     */
+    label?: string;
+    /**
+     * the nav landmark name; defaults to the label, then the id.
+     */
+    ariaLabel?: string;
+    items: AppSidebarItem[];
+};
+export type AppSidebarAccount = {
+    /**
+     * shown as
+     */
+    handle: string;
+};
+export type AppSidebarProps = {
+    /**
+     * which app renders the sidebar; marks its switcher entry current.
+     */
+    app: "online" | "local" | "docs" | string;
+    /**
+     * the app switcher entries (default APP_SIDEBAR_APPS, no hrefs).
+     */
+    apps?: AppSidebarApp[];
+    groups: AppSidebarGroup[];
+    /**
+     * the id of the current item (aria-current="page").
+     */
+    currentId?: string;
+    /**
+     * the brand links here.
+     */
+    homeHref?: string;
+    /**
+     * the wordmark, default 'peasant'.
+     */
+    brand?: string;
+    account?: AppSidebarAccount;
+    /**
+     * replaces the default account row content.
+     */
+    accountSlot?: import("react").ReactNode;
+    /**
+     * a router link; receives href, className,
+     * aria-current, title, target, rel, onClick and children.
+     */
+    LinkComponent?: import("react").ComponentType<any>;
+    /**
+     * localStorage key prefix, default 'fairtrade.app-sidebar'; null disables persistence.
+     */
+    storageKey?: string | null;
+    defaultCollapsed?: boolean;
+    /**
+     * px, default 248.
+     */
+    defaultWidth?: number;
+    /**
+     * px, default 200.
+     */
+    minWidth?: number;
+    /**
+     * px, default 360.
+     */
+    maxWidth?: number;
+    onCollapsedChange?: (collapsed: boolean) => void;
+    /**
+     * the aside's accessible name, default 'peasant'.
+     */
+    label?: string;
+    className?: string;
+};
+export type AppSidebarLayoutProps = {
+    /**
+     * an <AppSidebar>.
+     */
+    sidebar: import("react").ReactNode;
+    /**
+     * the page body.
+     */
+    children: import("react").ReactNode;
+    className?: string;
+};

package/dist/lib/types/index.d.ts

@@ -31,6 +31,12 @@ export { default as VillageObservations } from "./VillageObservations.jsx";
 export * from "./transcript/index.js";
 export * from "./transcript/graph/index.js";
 export type TimelineNavigationAction = import("./graph/timelineNavigation.js").TimelineNavigationAction;
+export type AppSidebarProps = import("./AppSidebar.jsx").AppSidebarProps;
+export type AppSidebarLayoutProps = import("./AppSidebar.jsx").AppSidebarLayoutProps;
+export type AppSidebarGroup = import("./AppSidebar.jsx").AppSidebarGroup;
+export type AppSidebarItem = import("./AppSidebar.jsx").AppSidebarItem;
+export type AppSidebarApp = import("./AppSidebar.jsx").AppSidebarApp;
+export type AppSidebarAccount = import("./AppSidebar.jsx").AppSidebarAccount;
 export type VillageObservationsProps = import("./VillageObservations.jsx").VillageObservationsProps;
 export type ObservationDomain = import("./VillageObservations.jsx").ObservationDomain;
 export type ObservedCollective = import("./VillageObservations.jsx").ObservedCollective;
@@ -61,6 +67,7 @@ export { default as ConsentDialog, ConsentSummary } from "./ConsentDialog.jsx";
 export { default as ModerationQueue, ApprovalBar } from "./ModerationQueue.jsx";
 export { default as RoleRoster, ConfirmInline, DangerZone } from "./RoleRoster.jsx";
 export { default as RailShell, RailSection, SplitRail } from "./RailShell.jsx";
+export { default as AppSidebar, AppSidebarLayout, APP_SIDEBAR_APPS } from "./AppSidebar.jsx";
 export { default as ProviderIcon, ProviderTag, ProviderName, AccentLegend, PROVIDER_ACCENT } from "./ProviderIcon.jsx";
 export { default as EvidenceCaption, EvidenceTarget } from "./EvidenceCaption.jsx";
 export { PhaseDivider, Phase, TaskBoundary, CheckpointMarker, TurnContextBar } from "./TranscriptMarkers.jsx";