@craftzbay/ui 0.5.0 → 0.6.0

package/dist-lib/components/patterns/AppShell.d.ts

@@ -1,12 +1,150 @@
 import { ReactNode } from 'react';
+/**
+ * Legacy nav keys retained for back-compat. The `active` prop now accepts
+ * any string — these are kept as a typed alias for consumers that hard-code
+ * one of the original demo values.
+ */
 export type AppShellNavKey = 'home' | 'projects' | 'inbox' | 'members' | 'insights' | 'bookmarks' | 'apps' | 'settings' | 'integrations' | 'help';
+export interface AppShellNavItem {
+    /** Active-state identifier — matches AppShell's `active` prop. */
+    key: string;
+    label: ReactNode;
+    /** Leading icon. */
+    icon?: ReactNode;
+    /** Destination. Renders as <a href>; for SPAs intercept onClick. */
+    href?: string;
+    /** Right-aligned content (Badge, count). */
+    trailing?: ReactNode;
+    /** Optional click handler. */
+    onClick?: () => void;
+}
+export interface AppShellNavSection {
+    /** Section heading shown above the items. */
+    label?: ReactNode;
+    items: AppShellNavItem[];
+}
+export interface AppShellUser {
+    name: ReactNode;
+    email?: ReactNode;
+    /** 1–2 char initials for the Avatar fallback. */
+    initials: string;
+    /** Online status — drives the Avatar status dot. */
+    status?: 'online' | 'busy' | 'away' | 'offline';
+}
+export interface AppShellNotification {
+    id: string;
+    who: {
+        name: string;
+        initials: string;
+    };
+    action: ReactNode;
+    target: ReactNode;
+    when: ReactNode;
+    unread?: boolean;
+    onClick?: () => void;
+}
+export interface AppShellProfileMenuItem {
+    label: ReactNode;
+    icon?: ReactNode;
+    trailing?: ReactNode;
+    onSelect?: () => void;
+    /** Renders a separator before this item. */
+    separatorAbove?: boolean;
+}
 export interface AppShellProps {
     /** Page content. */
     children: ReactNode;
     /** Logo / wordmark rendered at the top of the sidebar. */
     brand: ReactNode;
-    /** Which sidebar item is active. Defaults to `home`. */
-    active?: AppShellNavKey;
+    /** Which sidebar item is active. Matches `AppShellNavItem.key`. Defaults to `'home'`. */
+    active?: string;
+    /**
+     * Sidebar nav sections. Defaults to the built-in demo nav. Pass an empty
+     * array to hide the nav entirely, or use `sidebar` for a fully custom rail.
+     */
+    navSections?: AppShellNavSection[];
+    /**
+     * Escape hatch: replace the entire Sidebar contents. Takes precedence over
+     * `navSections`. Use when you need custom section components, groups, etc.
+     */
+    sidebar?: ReactNode;
+    /** Slot for additional topbar actions (left of notifications). */
+    topbarActions?: ReactNode;
+    /** Topbar search input — pass `false` to hide. */
+    search?: ReactNode | false;
+    /** Currently signed-in user, shown in the sidebar footer + profile menu. */
+    user?: AppShellUser;
+    /** Profile dropdown items. Defaults to the demo Profile / Settings / Sign out menu. */
+    profileMenu?: AppShellProfileMenuItem[];
+    /** Notification feed. Set to an empty array to hide the bell entirely. */
+    notifications?: AppShellNotification[];
+    /** Fires when the user clicks "Mark all read". */
+    onMarkAllNotificationsRead?: () => void;
+    /** Fires when the user clicks "View all" in the notifications menu. */
+    onViewAllNotifications?: () => void;
+}
+/**
+ * AppShell — sticky sidebar + topbar shell for SaaS dashboards.
+ *
+ * @example Default — uses the built-in demo nav, user, notifications
+ *   <AppShell brand={<Logo />} active="home">
+ *     <Dashboard />
+ *   </AppShell>
+ *
+ * @example Custom nav + user
+ *   <AppShell
+ *     brand={<Logo />}
+ *     active="projects"
+ *     user={{ name: 'Avery Long', email: 'avery@acme.com', initials: 'AL', status: 'online' }}
+ *     navSections={[
+ *       { label: 'Workspace', items: [
+ *         { key: 'home', label: 'Home', icon: <Home />, href: '/' },
+ *         { key: 'projects', label: 'Projects', icon: <Folder />, href: '/projects',
+ *           trailing: <Badge tone="neutral">{count}</Badge> },
+ *       ]},
+ *     ]}
+ *     notifications={data?.notifications ?? []}
+ *   >
+ *     <ProjectsPage />
+ *   </AppShell>
+ */
+export declare function AppShell({ children, brand, active, navSections, sidebar, topbarActions, search, user, profileMenu, notifications, onMarkAllNotificationsRead, onViewAllNotifications, }: AppShellProps): import("react/jsx-runtime").JSX.Element;
+export interface DashboardStat {
+    label: ReactNode;
+    value: ReactNode;
+    delta?: {
+        value: string;
+        positive?: boolean;
+    };
+}
+export interface DashboardActivityRow {
+    id: string;
+    who: {
+        name: string;
+        initials: string;
+    };
+    action: ReactNode;
+    target: ReactNode;
+    when: ReactNode;
+}
+export interface DashboardProps {
+    /** Top heading. */
+    title?: ReactNode;
+    /** Subtitle below the heading. */
+    subtitle?: ReactNode;
+    /** Top-right slot (date-range picker, segmented control, …). */
+    headerActions?: ReactNode;
+    /** Stat cards rendered in a responsive grid. */
+    stats?: DashboardStat[];
+    /** Chart card — any ReactNode (Chart component, SVG, image, placeholder). */
+    chart?: ReactNode;
+    /** Title above the chart. */
+    chartTitle?: ReactNode;
+    /** Subtitle under the chart title. */
+    chartDescription?: ReactNode;
+    /** Activity table rows. */
+    activity?: DashboardActivityRow[];
+    /** Title for the activity table. */
+    activityTitle?: ReactNode;
 }
-export declare function AppShell({ children, brand, active }: AppShellProps): import("react/jsx-runtime").JSX.Element;
-export declare function Dashboard(): import("react/jsx-runtime").JSX.Element;
+export declare function Dashboard({ title, subtitle, headerActions, stats, chart, chartTitle, chartDescription, activity, activityTitle, }?: DashboardProps): import("react/jsx-runtime").JSX.Element;

package/dist-lib/components/ui/EmptyState.d.ts

@@ -1,7 +1,16 @@
 import { HTMLAttributes, ReactNode } from 'react';
 export interface EmptyStateProps extends Omit<HTMLAttributes<HTMLDivElement>, 'title'> {
-    /** Visual marker — small Lucide icon or custom illustration. */
+    /**
+     * Small Lucide-sized icon rendered inside a 48px circular container.
+     * Use for compact empty states (table cells, sidebar panes, cards).
+     */
     icon?: ReactNode;
+    /**
+     * Full-size illustration rendered without the icon container. Takes
+     * precedence over `icon`. If neither is set, the default `InboxEmpty`
+     * line illustration is used.
+     */
+    illustration?: ReactNode;
     /** Heading. One short sentence. */
     title: ReactNode;
     /** Description. One or two sentences max. */
@@ -15,17 +24,23 @@ export interface EmptyStateProps extends Omit<HTMLAttributes<HTMLDivElement>, 't
  * Shown when a list / dataset / surface has no content yet. Tone is helpful,
  * never apologetic.
  *
- * @example
+ * @example Default — uses the built-in InboxEmpty illustration
  *   <EmptyState
- *     icon={<Folder className="size-6" />}
  *     title="No projects yet"
  *     description="Create a project to start tracking work."
  *     action={<Button>New project</Button>}
  *   />
  *
- * @do Lead with the next action. The icon is decoration; the button is the
- *      point.
- * @dont Use elaborate illustrations on internal product surfaces — they
- *       break the refined-minimal direction.
+ * @example Compact — small Lucide icon for dense layouts
+ *   <EmptyState
+ *     icon={<Folder className="size-6" />}
+ *     title="No items"
+ *   />
+ *
+ * @example Custom illustration
+ *   <EmptyState
+ *     illustration={<Illustrations.NoSearchResults className="size-32" />}
+ *     title="No results"
+ *   />
  */
 export declare const EmptyState: import('react').ForwardRefExoticComponent<EmptyStateProps & import('react').RefAttributes<HTMLDivElement>>;

package/dist-lib/components/ui/ErrorState.d.ts

@@ -6,6 +6,11 @@ export interface ErrorStateProps extends Omit<HTMLAttributes<HTMLDivElement>, 't
     title?: ReactNode;
     /** Override the default description. */
     description?: ReactNode;
+    /**
+     * Override the variant's default illustration. Pass any ReactNode (e.g.
+     * `<Illustrations.Construction className="size-32" />`).
+     */
+    illustration?: ReactNode;
     /** Custom action node. Replaces the default retry button. */
     action?: ReactNode;
     /** When provided, renders a default "Try again" button calling this handler. */
@@ -14,13 +19,19 @@ export interface ErrorStateProps extends Omit<HTMLAttributes<HTMLDivElement>, 't
 /**
  * Page-level error placeholder. Pair with `onRetry` for transient failures.
  *
- * @example 500
+ * @example 404 (uses built-in line illustration)
+ *   <ErrorState variant="404" />
+ *
+ * @example 500 with retry
  *   <ErrorState variant="500" onRetry={refetch} />
  *
  * @example Custom
- *   <ErrorState title="Quota exceeded"
- *               description="Your plan allows 1,000 events/day."
- *               action={<Button>Upgrade plan</Button>} />
+ *   <ErrorState
+ *     title="Quota exceeded"
+ *     description="Your plan allows 1,000 events/day."
+ *     illustration={<Illustrations.Construction className="size-32" />}
+ *     action={<Button>Upgrade plan</Button>}
+ *   />
  *
  * @do Match the tone to the cause — server errors apologise, user errors
  *      explain. Always offer a next step.