@craftzbay/ui 0.3.0 → 0.5.0

package/README.md

@@ -5,7 +5,8 @@ primitives — Button through DataGrid — plus composed patterns
 (authentication, app shell, settings, etc.).
 
 - **Showcase:** [design.runestonetechnologies.com](https://design.runestonetechnologies.com)
-- **Storybook:** [design.runestonetechnologies.com/storybook](https://design.runestonetechnologies.com/storybook/)
+- **Components catalog:** [design.runestonetechnologies.com#catalog](https://design.runestonetechnologies.com#catalog)
+- **Docs:** [design.runestonetechnologies.com#docs](https://design.runestonetechnologies.com#docs)
 
 > **Aesthetic direction:** Linear / Vercel / Stripe Dashboard / Notion / Raycast.
 > Neutral-dominant, one accent, hairline borders, generous whitespace, fast quiet
@@ -33,7 +34,6 @@ Peer dependencies: `react@>=18`, `react-dom@>=18`.
 ```bash
 pnpm install
 pnpm dev           # Vite showcase at localhost:5173
-pnpm storybook     # Storybook at localhost:6006
 pnpm build:lib     # Build library → dist-lib/
 ```
 

package/dist-lib/catalog.d.ts

@@ -0,0 +1,8 @@
+import { ReactNode } from 'react';
+export interface CatalogEntry {
+    name: string;
+    storyId: string;
+    group: string;
+    render: () => ReactNode;
+}
+export declare function useCatalogEntries(): CatalogEntry[];

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

@@ -1 +1,81 @@
-export declare function DataTablePage(): import("react/jsx-runtime").JSX.Element;
+import { ReactNode } from 'react';
+import { ButtonProps } from '../ui/Button';
+import { DataGridColumn } from '../ui/DataGrid';
+export interface DataTableFilter {
+    /** Field key used by the default predicate, and as the React key. */
+    key: string;
+    label: string;
+    /** First option should be the "all" / cleared value. */
+    options: {
+        value: string;
+        label: string;
+    }[];
+    /** Initial value. Defaults to the first option's value. */
+    defaultValue?: string;
+}
+export interface DataTableBulkAction<T> {
+    label: string;
+    /** Optional leading icon. */
+    icon?: ReactNode;
+    variant?: ButtonProps['variant'];
+    /** Receives the selected rows. Awaited — toolbar shows a spinner while pending. */
+    onAction: (selected: T[]) => void | Promise<void>;
+}
+export interface DataTablePageProps<T extends {
+    id: string | number;
+}> {
+    /** Page heading. */
+    title?: ReactNode;
+    /** Optional subtitle — defaults to a row-count line. */
+    subtitle?: ReactNode;
+    /** Right-aligned header actions (e.g. New / Import buttons). */
+    headerActions?: ReactNode;
+    /** Row data. */
+    rows?: T[];
+    /** Column descriptors. */
+    columns?: DataGridColumn<T>[];
+    /** Filter selects to render in the toolbar. */
+    filters?: DataTableFilter[];
+    /** Custom predicate. Receives the row + the active filter values. */
+    predicate?: (row: T, filterValues: Record<string, string>, search: string) => boolean;
+    /** Search placeholder. */
+    searchPlaceholder?: string;
+    /** Available rows-per-page sizes. */
+    pageSizeOptions?: number[];
+    /** Initial page size. */
+    defaultPageSize?: number;
+    /** Bulk-action buttons shown when rows are selected. */
+    bulkActions?: DataTableBulkAction<T>[];
+    /** EmptyState rendered when the filtered rows are empty. */
+    emptyState?: ReactNode;
+    className?: string;
+}
+/**
+ * Generic data-table page.
+ *
+ * @example
+ *   interface User { id: string; name: string; role: string; status: 'active' | 'invited' }
+ *
+ *   <DataTablePage<User>
+ *     title="Members"
+ *     rows={users}
+ *     columns={[
+ *       { key: 'name', header: 'Name', sortable: true },
+ *       { key: 'role', header: 'Role' },
+ *       { key: 'status', header: 'Status', cell: (r) => <Badge>{r.status}</Badge> },
+ *     ]}
+ *     filters={[
+ *       { key: 'status', label: 'Status', options: [
+ *         { value: 'all', label: 'All' },
+ *         { value: 'active', label: 'Active' },
+ *         { value: 'invited', label: 'Invited' },
+ *       ]},
+ *     ]}
+ *     bulkActions={[
+ *       { label: 'Remove', variant: 'destructive', onAction: (rows) => api.remove(rows) },
+ *     ]}
+ *   />
+ */
+export declare function DataTablePage<T extends {
+    id: string | number;
+}>({ title, subtitle, headerActions, rows: rowsProp, columns: columnsProp, filters: filtersProp, predicate, searchPlaceholder, pageSizeOptions, defaultPageSize, bulkActions: bulkActionsProp, emptyState, className, }?: DataTablePageProps<T>): import("react/jsx-runtime").JSX.Element;

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

@@ -1 +1,39 @@
-export declare function FirstRunEmpty(): import("react/jsx-runtime").JSX.Element;
+import { ReactNode } from 'react';
+export interface FirstRunNextStep {
+    icon?: ReactNode;
+    title: string;
+    description: string;
+    cta: string;
+    onSelect?: () => void;
+}
+export interface FirstRunEmptyProps {
+    /** Hero icon — typically a folder, sparkles, or product mark. */
+    heroIcon?: ReactNode;
+    /** Hero title. */
+    title?: ReactNode;
+    /** Hero subtitle. */
+    description?: ReactNode;
+    /** Primary CTA inside the hero (top tutorial / overview action). */
+    primaryAction?: ReactNode;
+    /** Next-step cards rendered below the hero. */
+    steps?: FirstRunNextStep[];
+    className?: string;
+}
+/**
+ * First-run empty product state.
+ *
+ * @example Default (uses built-in placeholder copy)
+ *   <FirstRunEmpty />
+ *
+ * @example Customized
+ *   <FirstRunEmpty
+ *     heroIcon={<Illustrations.InboxEmpty className="size-16" />}
+ *     title="Welcome to Atlas"
+ *     description="Pick a starting point."
+ *     steps={[
+ *       { icon: <Plus />, title: 'New project', description: '…', cta: 'Create' },
+ *       { icon: <Github />, title: 'Import repo', description: '…', cta: 'Connect' },
+ *     ]}
+ *   />
+ */
+export declare function FirstRunEmpty({ heroIcon, title, description, primaryAction, steps, className, }?: FirstRunEmptyProps): import("react/jsx-runtime").JSX.Element;

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

@@ -1 +1,65 @@
-export declare function Onboarding(): import("react/jsx-runtime").JSX.Element;
+import { ReactNode } from 'react';
+export interface OnboardingStepContext<T = unknown> {
+    /** Move to the next step. */
+    next: () => void;
+    /** Move to the previous step. */
+    prev: () => void;
+    /** Jump to a step by index. */
+    goTo: (index: number) => void;
+    /** Finish the flow — calls onComplete. */
+    finish: () => void;
+    /** Current accumulated data across steps. */
+    data: T;
+    /** Patch the accumulated data. */
+    setData: (patch: Partial<T>) => void;
+}
+export interface OnboardingStep<T = unknown> {
+    /** Stable id used for keys + analytics. */
+    id: string;
+    /** Title shown in the Stepper. */
+    title: string;
+    /** Optional sub-description shown only in vertical Stepper. */
+    description?: string;
+    /** Card heading rendered when the step is active. */
+    heading: ReactNode;
+    /** Card description rendered under the heading. */
+    subheading?: ReactNode;
+    /** Step body. Receives navigation controls + shared data. */
+    render: (ctx: OnboardingStepContext<T>) => ReactNode;
+    /** Override the Continue / Finish button label. */
+    ctaLabel?: string;
+    /** Hide the default Back/Next bar — render your own inside `render`. */
+    hideNavigation?: boolean;
+}
+export interface OnboardingProps<T = unknown> {
+    steps?: OnboardingStep<T>[];
+    /** Initial accumulated data. */
+    initialData?: T;
+    /** Called when the user advances past the last step. */
+    onComplete?: (data: T) => void | Promise<void>;
+    className?: string;
+}
+interface DemoData {
+    workspaceName?: string;
+    slug?: string;
+    inviteEmail?: string;
+    role?: string;
+    source?: string;
+}
+/**
+ * Multi-step onboarding wizard.
+ *
+ * @example
+ *   <Onboarding<{ name: string; email: string }>
+ *     initialData={{ name: '', email: '' }}
+ *     steps={[
+ *       { id: 'name', title: 'Name', heading: 'What should we call you?',
+ *         render: ({ data, setData }) =>
+ *           <Input value={data.name} onChange={(e) => setData({ name: e.target.value })} /> },
+ *       …
+ *     ]}
+ *     onComplete={async (data) => api.completeOnboarding(data)}
+ *   />
+ */
+export declare function Onboarding<T = DemoData>({ steps, initialData, onComplete, className, }?: OnboardingProps<T>): import("react/jsx-runtime").JSX.Element;
+export {};

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

@@ -1 +1,40 @@
-export declare function Pricing(): import("react/jsx-runtime").JSX.Element;
+import { ReactNode } from 'react';
+export interface PricingTier {
+    name: string;
+    /** Price string. Pre-formatted — render '$0', '$20', 'Custom', '¥1,200', etc. */
+    price: string;
+    /** Cadence label rendered next to the price ('per user / month'). */
+    cadence?: string;
+    description?: string;
+    features: string[];
+    /** CTA label. */
+    cta: string;
+    /** Mark this tier as the recommended one — adds accent border + badge. */
+    highlighted?: boolean;
+    /** Click handler for the CTA. */
+    onSelect?: () => void;
+}
+export interface PricingProps {
+    /** Top heading. */
+    title?: ReactNode;
+    /** Subtitle under the heading. */
+    subtitle?: ReactNode;
+    /** Tier descriptors. */
+    tiers?: PricingTier[];
+    /** Label shown on the highlighted tier badge. */
+    highlightedLabel?: string;
+    className?: string;
+}
+/**
+ * Pricing grid. Defaults to a 3-tier demo if `tiers` is omitted.
+ *
+ * @example
+ *   <Pricing
+ *     title="Plans"
+ *     tiers={[
+ *       { name: 'Free', price: '$0', features: ['…'], cta: 'Start' },
+ *       { name: 'Pro', price: '$12', features: ['…'], cta: 'Upgrade', highlighted: true },
+ *     ]}
+ *   />
+ */
+export declare function Pricing({ title, subtitle, tiers, highlightedLabel, className, }?: PricingProps): import("react/jsx-runtime").JSX.Element;

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

@@ -1 +1,48 @@
-export declare function RecordDetail(): import("react/jsx-runtime").JSX.Element;
+import { ReactNode } from 'react';
+export interface RecordDetailHeader {
+    title: ReactNode;
+    subtitle?: ReactNode;
+    /** Optional status pill rendered next to the title. */
+    status?: ReactNode;
+    /** Right-aligned action buttons. */
+    actions?: ReactNode;
+    /** Breadcrumb trail rendered above the header. */
+    breadcrumbs?: {
+        label: ReactNode;
+        href?: string;
+    }[];
+}
+export interface RecordDetailTab {
+    id: string;
+    label: ReactNode;
+    render: () => ReactNode;
+}
+export interface RecordDetailProps {
+    header?: RecordDetailHeader;
+    tabs?: RecordDetailTab[];
+    /** Initial tab id. Defaults to the first tab. */
+    defaultTab?: string;
+    /** Optional right-side panel (related items, details list, watchers, …). */
+    sidePanel?: ReactNode;
+    className?: string;
+}
+/**
+ * Record detail page — header (breadcrumbs + title + actions) + tabs + side panel.
+ *
+ * @example
+ *   <RecordDetail
+ *     header={{
+ *       title: project.name,
+ *       subtitle: project.description,
+ *       status: <Badge tone="success">Active</Badge>,
+ *       actions: <Button>Share</Button>,
+ *       breadcrumbs: [{ label: 'Projects', href: '/projects' }, { label: project.name }],
+ *     }}
+ *     tabs={[
+ *       { id: 'overview', label: 'Overview', render: () => <Overview project={project} /> },
+ *       { id: 'activity', label: 'Activity', render: () => <Activity projectId={project.id} /> },
+ *     ]}
+ *     sidePanel={<RelatedItems project={project} />}
+ *   />
+ */
+export declare function RecordDetail({ header, tabs, defaultTab, sidePanel, className, }?: RecordDetailProps): import("react/jsx-runtime").JSX.Element;

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

@@ -1 +1,34 @@
-export declare function SettingsPage(): import("react/jsx-runtime").JSX.Element;
+import { ReactNode } from 'react';
+export interface SettingsSection {
+    id: string;
+    label: string;
+    icon?: ReactNode;
+    render: () => ReactNode;
+}
+export interface SettingsPageProps {
+    /** Page title — defaults to "Settings". */
+    title?: ReactNode;
+    /** Subtitle under the heading. */
+    subtitle?: ReactNode;
+    sections?: SettingsSection[];
+    /** Initially active section id. Defaults to the first section. */
+    defaultSection?: string;
+    /** Controlled active section id. */
+    activeSection?: string;
+    /** Fires when the active section changes (controlled mode). */
+    onActiveSectionChange?: (id: string) => void;
+    className?: string;
+}
+/**
+ * Settings page with a sticky sub-nav on the left and section cards on the right.
+ *
+ * @example
+ *   <SettingsPage
+ *     sections={[
+ *       { id: 'profile', label: 'Profile', icon: <User />, render: () => <ProfileForm /> },
+ *       { id: 'team', label: 'Team', icon: <Users />, render: () => <TeamForm /> },
+ *     ]}
+ *     defaultSection="profile"
+ *   />
+ */
+export declare function SettingsPage({ title, subtitle, sections, defaultSection, activeSection, onActiveSectionChange, className, }?: SettingsPageProps): import("react/jsx-runtime").JSX.Element;

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

@@ -3,7 +3,7 @@ import { VariantProps } from '../../lib/cva';
 declare const alert: (props?: ({
     variant?: "default" | "success" | "warning" | "danger" | "info" | null | undefined;
 } & import('class-variance-authority/types').ClassProp) | undefined) => string;
-export interface AlertProps extends HTMLAttributes<HTMLDivElement>, VariantProps<typeof alert> {
+export interface AlertProps extends Omit<HTMLAttributes<HTMLDivElement>, 'title'>, VariantProps<typeof alert> {
     /** Heading. Renders bold above the description. */
     title?: ReactNode;
     /** Show a dismiss (×) button. */

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

@@ -0,0 +1,60 @@
+import { HTMLAttributes, ReactNode } from 'react';
+/**
+ * Per-brand token overrides. Keys are CSS variable names (without the `--`
+ * prefix); values are CSS values. Any unspecified token falls back to the
+ * design system default.
+ *
+ * @example
+ *   <DesignSystemProvider tokens={{ 'color-accent': '#ff5555', 'radius-md': '10px' }}>
+ *     <App />
+ *   </DesignSystemProvider>
+ *
+ * @example Multiple brands in one app
+ *   <DesignSystemProvider tokens={edgelogBrand}>
+ *     <Card>...</Card>
+ *   </DesignSystemProvider>
+ *   <DesignSystemProvider tokens={geregeBrand}>
+ *     <Card>...</Card>
+ *   </DesignSystemProvider>
+ */
+export type BrandTokens = Record<string, string>;
+export interface DesignSystemProviderProps extends HTMLAttributes<HTMLDivElement> {
+    /** Token overrides (CSS variable name → value). */
+    tokens?: BrandTokens;
+    /** Children to scope this brand to. */
+    children: ReactNode;
+}
+export declare function DesignSystemProvider({ tokens, className, children, style, ...props }: DesignSystemProviderProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * Built-in brand presets — drop-in starters showing how a token override
+ * map is shaped. Consumers can fork or replace any value.
+ */
+export declare const brandPresets: {
+    readonly default: BrandTokens;
+    /** Cool indigo accent, slightly rounder corners. */
+    readonly edgelog: {
+        readonly 'color-accent': "oklch(0.55 0.18 250)";
+        readonly 'color-accent-700': "oklch(0.46 0.16 250)";
+        readonly 'color-accent-800': "oklch(0.38 0.14 250)";
+        readonly 'color-accent-soft': "oklch(0.95 0.04 250)";
+        readonly 'radius-md': "8px";
+        readonly 'radius-lg': "12px";
+    };
+    /** Warm copper accent, tighter geometry. */
+    readonly gerege: {
+        readonly 'color-accent': "oklch(0.62 0.16 45)";
+        readonly 'color-accent-700': "oklch(0.54 0.16 45)";
+        readonly 'color-accent-800': "oklch(0.46 0.14 45)";
+        readonly 'color-accent-soft': "oklch(0.95 0.04 45)";
+        readonly 'radius-md': "4px";
+        readonly 'radius-lg': "6px";
+    };
+    /** Forest green accent. */
+    readonly forest: {
+        readonly 'color-accent': "oklch(0.55 0.14 155)";
+        readonly 'color-accent-700': "oklch(0.47 0.14 155)";
+        readonly 'color-accent-800': "oklch(0.39 0.12 155)";
+        readonly 'color-accent-soft': "oklch(0.95 0.04 155)";
+    };
+};
+export type BrandName = keyof typeof brandPresets;

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

@@ -1,5 +1,5 @@
 import { HTMLAttributes, ReactNode } from 'react';
-export interface EmptyStateProps extends HTMLAttributes<HTMLDivElement> {
+export interface EmptyStateProps extends Omit<HTMLAttributes<HTMLDivElement>, 'title'> {
     /** Visual marker — small Lucide icon or custom illustration. */
     icon?: ReactNode;
     /** Heading. One short sentence. */

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

@@ -1,5 +1,5 @@
 import { HTMLAttributes, ReactNode } from 'react';
-export interface ErrorStateProps extends HTMLAttributes<HTMLDivElement> {
+export interface ErrorStateProps extends Omit<HTMLAttributes<HTMLDivElement>, 'title'> {
     /** `404` not-found, `500` server, or `generic` (catch-all). */
     variant?: '404' | '500' | 'generic';
     /** Override the default title. */

package/dist-lib/hooks/use-toast.d.ts

@@ -34,10 +34,10 @@ interface InternalToast extends ToastDescriptor {
  */
 export declare function useToast(): {
     toasts: InternalToast[];
-    push: (t: ToastDescriptor) => any;
-    dismiss: (id: string) => any;
-    remove: (id: string) => any;
+    push: (t: ToastDescriptor) => string;
+    dismiss: (id: string) => void;
+    remove: (id: string) => void;
 };
 /** Convenience export — dispatch a toast outside React (e.g. from an API client). */
-export declare const toast: (t: ToastDescriptor) => any;
+export declare const toast: (t: ToastDescriptor) => string;
 export {};

package/dist-lib/icons/index.d.ts

@@ -8,4 +8,4 @@
  *   - 20px for use inside buttons
  *   - strokeWidth 1.5
  */
-export { AlertCircle, AlertTriangle, ArrowDown, ArrowLeft, ArrowRight, ArrowUp, ArrowUpDown, BarChart3, Bell, Bookmark, Calendar, Check, CheckCircle2, ChevronDown, ChevronLeft, ChevronRight, ChevronUp, ChevronsLeft, ChevronsRight, ChevronsUpDown, Circle, Copy, CornerDownLeft, CreditCard, Download, Edit2, Ellipsis, Eye, EyeOff, Filter, Folder, GripVertical, Home, Inbox, LayoutGrid, Lock, LogOut, HelpCircle, Info, Link2, Loader2, Mail, Menu, Minus, MoreHorizontal, Plug, Plus, Search, Sparkles, Settings, Sun, Moon, Trash2, Upload, User, Users, X, XCircle, ExternalLink, type LucideIcon, type LucideProps, } from 'lucide-react';
+export { AlertCircle, AlertTriangle, ArrowDown, ArrowLeft, ArrowRight, ArrowUp, ArrowUpDown, AtSign, BarChart3, Bell, Bookmark, Calendar, Check, CheckCircle2, ChevronDown, ChevronLeft, ChevronRight, ChevronUp, ChevronsLeft, ChevronsRight, ChevronsUpDown, Circle, Copy, CornerDownLeft, CreditCard, Download, Edit2, Ellipsis, Eye, EyeOff, Filter, Folder, GripVertical, Home, Inbox, LayoutGrid, Lock, LogOut, HelpCircle, Info, Link2, Loader2, Mail, Menu, Minus, MoreHorizontal, Package, Plug, Plus, Search, Sparkles, Settings, Sun, Moon, Trash2, Upload, User, Users, X, XCircle, ExternalLink, type LucideIcon, type LucideProps, } from 'lucide-react';