@geenius/storybook 0.1.0

package/dist/surface.d.ts

@@ -0,0 +1,45 @@
+import { StorySurface, StorySurfaceSection, StorySurfaceEntry } from './types.js';
+import 'vite';
+
+/**
+ * Define a story surface with type-safety.
+ * The `as const satisfies` pattern is applied by the consumer; this helper
+ * validates and returns the surface unchanged.
+ */
+declare function defineSurface<const T extends StorySurface>(surface: T): T;
+/** Extract a flat array of all story IDs from a surface. */
+declare function getSurfaceIds(surface: StorySurface): string[];
+/** Extract a flat array of all story entries from a surface. */
+declare function getSurfaceEntries(surface: StorySurface): StorySurfaceEntry[];
+/** Get the total component count across all sections. */
+declare function getSurfaceComponentCount(surface: StorySurface): number;
+/** Look up a story entry by ID. Returns `undefined` if not found. */
+declare function findSurfaceEntry(surface: StorySurface, id: string): StorySurfaceEntry | undefined;
+/** Look up which section a story belongs to. */
+declare function findSurfaceSection(surface: StorySurface, storyId: string): StorySurfaceSection | undefined;
+/**
+ * Filter a surface by a search query (case-insensitive match against
+ * story label, id, or description). Returns a new surface with only
+ * matching entries, omitting empty sections.
+ */
+declare function filterSurface(surface: StorySurface, query: string): StorySurfaceSection[];
+/**
+ * Create a JSON-serialisable snapshot of the surface for testing
+ * or documentation generation.
+ */
+declare function getSurfaceSnapshot(surface: StorySurface): {
+    title: string;
+    stories: {
+        id: string;
+        label: string;
+        description?: string;
+        tags?: readonly string[];
+    }[];
+}[];
+/**
+ * Validate that all story IDs in a surface are unique.
+ * Returns an array of duplicate IDs (empty if valid).
+ */
+declare function validateSurface(surface: StorySurface): string[];
+
+export { StorySurface, StorySurfaceEntry, StorySurfaceSection, defineSurface, filterSurface, findSurfaceEntry, findSurfaceSection, getSurfaceComponentCount, getSurfaceEntries, getSurfaceIds, getSurfaceSnapshot, validateSurface };

package/dist/surface.js

@@ -0,0 +1,3 @@
+export { defineSurface, filterSurface, findSurfaceEntry, findSurfaceSection, getSurfaceComponentCount, getSurfaceEntries, getSurfaceIds, getSurfaceSnapshot, validateSurface } from './chunk-FB7KPF72.js';
+//# sourceMappingURL=surface.js.map
+//# sourceMappingURL=surface.js.map

package/dist/surface.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"surface.js"}

package/dist/theme.css

@@ -0,0 +1,246 @@
+/* ============================================================================
+   @geenius/storybook — Component Theme (Dark / Light)
+   ============================================================================
+   Design tokens for the components being showcased. This file provides the
+   semantic color variables that component libraries (ui-react, ui-solidjs, etc.)
+   reference via `var(--primary)`, `var(--border)`, and so on.
+
+   Import this in your storybook app's CSS alongside `@geenius/storybook/styles`
+   so that both the shell and the components share the same token space.
+   ============================================================================ */
+
+:root {
+  color-scheme: dark;
+
+  /* Backgrounds */
+  --background: oklch(0.08 0.01 260);
+  --foreground: oklch(0.96 0.01 250);
+
+  --card: oklch(0.12 0.01 260);
+  --card-foreground: oklch(0.96 0.01 250);
+
+  --popover: oklch(0.12 0.01 260);
+  --popover-foreground: oklch(0.96 0.01 250);
+
+  /* Primary */
+  --primary: oklch(0.72 0.2 265);
+  --primary-foreground: oklch(0.12 0.01 260);
+
+  /* Secondary */
+  --secondary: oklch(0.2 0.01 260);
+  --secondary-foreground: oklch(0.96 0.01 250);
+
+  /* Muted */
+  --muted: oklch(0.18 0.01 260);
+  --muted-foreground: oklch(0.64 0.02 250);
+
+  /* Accent */
+  --accent: oklch(0.2 0.01 260);
+  --accent-foreground: oklch(0.96 0.01 250);
+
+  /* Destructive / Danger */
+  --destructive: oklch(0.62 0.22 25);
+  --destructive-foreground: oklch(0.98 0.01 260);
+  --danger: oklch(0.62 0.22 25);
+  --danger-foreground: oklch(0.98 0.01 260);
+
+  /* Semantic */
+  --success: oklch(0.72 0.18 155);
+  --success-foreground: oklch(0.12 0.01 260);
+
+  --warning: oklch(0.78 0.18 75);
+  --warning-foreground: oklch(0.12 0.01 260);
+
+  --error: oklch(0.62 0.22 25);
+  --error-foreground: oklch(0.98 0.01 260);
+
+  --info: oklch(0.72 0.2 265);
+  --info-foreground: oklch(0.12 0.01 260);
+
+  /* Structural */
+  --border: oklch(0.24 0.01 260);
+  --border-hover: oklch(0.3 0.01 260);
+  --input: oklch(0.24 0.01 260);
+  --ring: oklch(0.7 0.2 265);
+
+  /* Surfaces */
+  --surface: oklch(0.15 0.01 260);
+  --surface-alt: oklch(0.18 0.01 260);
+  --bg-muted: oklch(0.16 0.01 260);
+
+  /* Aliases */
+  --text-main: var(--foreground);
+  --text-muted: var(--muted-foreground);
+
+  /* Radius scale */
+  --radius: 0.5rem;
+}
+
+/* ---------------------------------------------------------------------------
+   Light Mode
+   --------------------------------------------------------------------------- */
+
+:root.light,
+[data-theme='light'] {
+  color-scheme: light;
+
+  --background: oklch(0.98 0.005 260);
+  --foreground: oklch(0.15 0.01 250);
+
+  --card: oklch(1 0 0);
+  --card-foreground: oklch(0.15 0.01 250);
+
+  --popover: oklch(1 0 0);
+  --popover-foreground: oklch(0.15 0.01 250);
+
+  --primary: oklch(0.55 0.22 265);
+  --primary-foreground: oklch(0.98 0.005 260);
+
+  --secondary: oklch(0.93 0.005 260);
+  --secondary-foreground: oklch(0.15 0.01 250);
+
+  --muted: oklch(0.93 0.005 260);
+  --muted-foreground: oklch(0.45 0.01 250);
+
+  --accent: oklch(0.93 0.005 260);
+  --accent-foreground: oklch(0.15 0.01 250);
+
+  --destructive: oklch(0.55 0.22 25);
+  --destructive-foreground: oklch(0.98 0.005 260);
+  --danger: oklch(0.55 0.22 25);
+  --danger-foreground: oklch(0.98 0.005 260);
+
+  --success: oklch(0.55 0.18 155);
+  --success-foreground: oklch(0.98 0.005 260);
+
+  --warning: oklch(0.65 0.18 75);
+  --warning-foreground: oklch(0.15 0.01 250);
+
+  --error: oklch(0.55 0.22 25);
+  --error-foreground: oklch(0.98 0.005 260);
+
+  --info: oklch(0.55 0.2 265);
+  --info-foreground: oklch(0.98 0.005 260);
+
+  --border: oklch(0.88 0.005 260);
+  --border-hover: oklch(0.8 0.005 260);
+  --input: oklch(0.88 0.005 260);
+  --ring: oklch(0.55 0.22 265);
+
+  --surface: oklch(0.96 0.005 260);
+  --surface-alt: oklch(0.93 0.005 260);
+  --bg-muted: oklch(0.95 0.005 260);
+
+  --text-main: var(--foreground);
+  --text-muted: var(--muted-foreground);
+}
+
+/* ---------------------------------------------------------------------------
+   Tailwind v4 Theme Integration
+   --------------------------------------------------------------------------- */
+
+@theme {
+  --color-background: var(--background);
+  --color-foreground: var(--foreground);
+
+  --color-card: var(--card);
+  --color-card-foreground: var(--card-foreground);
+
+  --color-popover: var(--popover);
+  --color-popover-foreground: var(--popover-foreground);
+
+  --color-primary: var(--primary);
+  --color-primary-foreground: var(--primary-foreground);
+
+  --color-secondary: var(--secondary);
+  --color-secondary-foreground: var(--secondary-foreground);
+
+  --color-muted: var(--muted);
+  --color-muted-foreground: var(--muted-foreground);
+
+  --color-accent: var(--accent);
+  --color-accent-foreground: var(--accent-foreground);
+
+  --color-destructive: var(--destructive);
+  --color-destructive-foreground: var(--destructive-foreground);
+
+  --color-danger: var(--danger);
+  --color-danger-foreground: var(--danger-foreground);
+
+  --color-success: var(--success);
+  --color-success-foreground: var(--success-foreground);
+
+  --color-warning: var(--warning);
+  --color-warning-foreground: var(--warning-foreground);
+
+  --color-error: var(--error);
+  --color-error-foreground: var(--error-foreground);
+
+  --color-info: var(--info);
+  --color-info-foreground: var(--info-foreground);
+
+  --color-border: var(--border);
+  --color-border-hover: var(--border-hover);
+  --color-input: var(--input);
+  --color-ring: var(--ring);
+
+  --color-surface: var(--surface);
+  --color-surface-alt: var(--surface-alt);
+  --color-bg-muted: var(--bg-muted);
+
+  --color-text-main: var(--text-main);
+  --color-text-muted: var(--text-muted);
+
+  --radius-sm: calc(var(--radius) - 0.25rem);
+  --radius-md: var(--radius);
+  --radius-lg: calc(var(--radius) + 0.25rem);
+  --radius-xl: calc(var(--radius) + 0.5rem);
+}
+
+/* ---------------------------------------------------------------------------
+   Tone Utilities — semantic color shorthands
+   --------------------------------------------------------------------------- */
+
+.tone-success {
+  --tone-bg: var(--success);
+  --tone-fg: var(--success-foreground);
+}
+
+.tone-warning {
+  --tone-bg: var(--warning);
+  --tone-fg: var(--warning-foreground);
+}
+
+.tone-danger {
+  --tone-bg: var(--danger);
+  --tone-fg: var(--danger-foreground);
+}
+
+.tone-info {
+  --tone-bg: var(--info);
+  --tone-fg: var(--info-foreground);
+}
+
+.tone-surface {
+  background-color: color-mix(in oklch, var(--tone-bg) 15%, transparent);
+  color: var(--tone-bg);
+  border-color: color-mix(in oklch, var(--tone-bg) 30%, transparent);
+}
+
+/* ---------------------------------------------------------------------------
+   Base HTML Styles
+   --------------------------------------------------------------------------- */
+
+html,
+body {
+  min-height: 100%;
+  background: var(--background);
+  color: var(--foreground);
+  font-family: system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
+}
+
+body {
+  text-rendering: optimizeLegibility;
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+}

package/dist/types.d.ts

@@ -0,0 +1,75 @@
+import * as vite from 'vite';
+
+/** A single story entry in the surface catalog. */
+type StorySurfaceEntry = {
+    /** Unique kebab-case identifier used in routing and registry lookups. */
+    id: string;
+    /** Human-readable label shown in the sidebar. */
+    label: string;
+    /** Optional short description shown beneath the label. */
+    description?: string;
+    /** Optional short tags surfaced in navigation and search. */
+    tags?: readonly string[];
+};
+/** A named section grouping related stories. */
+type StorySurfaceSection = {
+    /** Section heading (e.g. "Primitives", "Form Controls"). */
+    title: string;
+    /** Ordered list of stories belonging to this section. */
+    stories: readonly StorySurfaceEntry[];
+};
+/** The full story surface — an ordered array of sections. */
+type StorySurface = readonly StorySurfaceSection[];
+/** Union of all story IDs derived from a given surface. */
+type StorySurfaceId<T extends StorySurface> = T[number]['stories'][number]['id'];
+/** View state: either a story ID or the dashboard landing. */
+type ActiveView<TId extends string = string> = TId | 'dashboard';
+/** Supported styling approach identifiers. */
+type StyleVariant = 'tailwind' | 'css';
+/** Supported UI framework identifiers. */
+type Framework = 'react' | 'solidjs' | 'vue' | 'svelte';
+/** Theme mode. */
+type ThemeMode = 'dark' | 'light' | 'system';
+/** Configuration for `createStorybookViteConfig`. */
+interface StorybookViteOptions {
+    /** Which UI framework this storybook app targets. */
+    framework: Framework;
+    /** Dev server port. */
+    port: number;
+    /** Vite plugins specific to the framework (e.g. `@vitejs/plugin-react`). */
+    plugins?: vite.PluginOption[];
+    /** Extra resolve aliases beyond the default `@` → `./src`. */
+    aliases?: Record<string, string>;
+    /** Override the default Tailwind CSS Vite plugin. Pass `false` to disable. */
+    tailwind?: vite.PluginOption | false;
+    /** Extra Vite config merged on top of the shared preset. */
+    config?: vite.UserConfig;
+}
+/** Metadata about the storybook instance, used in dashboard and shell chrome. */
+interface StorybookMeta {
+    /** Package name being showcased (e.g. "@geenius/ui"). */
+    packageName: string;
+    /** Human-friendly title (e.g. "Geenius UI"). */
+    title: string;
+    /** Subtitle shown under the sidebar title (e.g. "React Component Storybook"). */
+    subtitle: string;
+    /** Current version string. */
+    version: string;
+    /** Style variants available in this storybook. */
+    styleVariants: readonly StyleVariant[];
+    /** Frameworks available across the family. */
+    frameworks: readonly Framework[];
+}
+/** Dashboard statistics derived from a story surface. */
+interface DashboardStats {
+    /** Total number of component stories. */
+    componentCount: number;
+    /** Number of sections / categories. */
+    sectionCount: number;
+    /** Number of style variants. */
+    styleVariantCount: number;
+    /** Number of framework implementations. */
+    frameworkCount: number;
+}
+
+export type { ActiveView, DashboardStats, Framework, StorySurface, StorySurfaceEntry, StorySurfaceId, StorySurfaceSection, StorybookMeta, StorybookViteOptions, StyleVariant, ThemeMode };

package/dist/types.js

@@ -0,0 +1,3 @@
+
+//# sourceMappingURL=types.js.map
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"types.js"}

package/dist/utils.d.ts

@@ -0,0 +1,42 @@
+import { StorySurface, StorybookMeta, DashboardStats, ActiveView, ThemeMode } from './types.js';
+import 'vite';
+
+/** Parse the current `window.location.hash` into an `ActiveView`. */
+declare function getHashRoute<TId extends string>(validIds: readonly TId[]): ActiveView<TId>;
+/** Push a new hash route without full page reload. */
+declare function setHashRoute(view: string): void;
+/** Read the stored theme preference, falling back to the given default. */
+declare function getStoredTheme(fallback?: ThemeMode): ThemeMode;
+/** Persist the theme preference. */
+declare function setStoredTheme(mode: ThemeMode): void;
+/**
+ * Resolve a theme mode to an effective `'dark' | 'light'` value,
+ * accounting for `'system'` by querying `prefers-color-scheme`.
+ */
+declare function resolveTheme(mode: ThemeMode): 'dark' | 'light';
+/**
+ * Apply the given effective theme to the document root.
+ * Sets the `data-theme` attribute and toggles the `light` class.
+ */
+declare function applyTheme(effective: 'dark' | 'light'): void;
+/** Compute dashboard statistics from a surface and meta. */
+declare function computeDashboardStats(surface: StorySurface, meta: StorybookMeta): DashboardStats;
+/** Key bindings for common storybook actions. */
+interface KeyboardShortcuts {
+    /** Toggle sidebar visibility (mobile). Default: `Escape` */
+    toggleSidebar: string;
+    /** Toggle theme mode. Default: `t` */
+    toggleTheme: string;
+    /** Focus search input. Default: `/` or `Cmd+K` */
+    focusSearch: string;
+    /** Navigate to dashboard. Default: `h` */
+    goHome: string;
+}
+declare const DEFAULT_SHORTCUTS: KeyboardShortcuts;
+/**
+ * Check whether a KeyboardEvent matches a shortcut string.
+ * Supports modifiers: `Cmd+K`, `Ctrl+Shift+P`, etc.
+ */
+declare function matchesShortcut(event: KeyboardEvent, shortcut: string): boolean;
+
+export { DEFAULT_SHORTCUTS, type KeyboardShortcuts, applyTheme, computeDashboardStats, getHashRoute, getStoredTheme, matchesShortcut, resolveTheme, setHashRoute, setStoredTheme };

package/dist/utils.js

@@ -0,0 +1,3 @@
+export { DEFAULT_SHORTCUTS, applyTheme, computeDashboardStats, getHashRoute, getStoredTheme, matchesShortcut, resolveTheme, setHashRoute, setStoredTheme } from './chunk-IEHIPVSX.js';
+//# sourceMappingURL=utils.js.map
+//# sourceMappingURL=utils.js.map

package/dist/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"utils.js"}

package/dist/vite.d.ts

@@ -0,0 +1,41 @@
+import * as vite from 'vite';
+import { StorybookViteOptions } from './types.js';
+
+/**
+ * Create a Vite configuration for a storybook app.
+ *
+ * @example
+ * ```ts
+ * // apps/storybook-react/vite.config.ts
+ * import { createStorybookViteConfig } from '@geenius/storybook/vite'
+ * import react from '@vitejs/plugin-react'
+ *
+ * export default createStorybookViteConfig({
+ *   framework: 'react',
+ *   port: 3050,
+ *   plugins: [react()],
+ * })
+ * ```
+ */
+declare function createStorybookViteConfig(options: StorybookViteOptions): Record<string, any> | {
+    plugins: vite.PluginOption[];
+    resolve: {
+        alias: {
+            '@': string;
+        };
+    };
+    server: {
+        port: number;
+        strictPort: false;
+    };
+    build: {
+        target: string;
+        sourcemap: true;
+    };
+    define: {
+        __GSB_FRAMEWORK__: string;
+        __GSB_PORT__: string;
+    };
+};
+
+export { StorybookViteOptions, createStorybookViteConfig };

package/dist/vite.js

@@ -0,0 +1,3 @@
+export { createStorybookViteConfig } from './chunk-PRS2B2OG.js';
+//# sourceMappingURL=vite.js.map
+//# sourceMappingURL=vite.js.map

package/dist/vite.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"vite.js"}

package/package.json

@@ -0,0 +1,103 @@
+{
+  "name": "@geenius/storybook",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Shared storybook shell, theme, layout, and Vite preset for all @geenius packages",
+  "license": "MIT",
+  "author": "Antigravity <dev@antigravity.dev>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/geenius-dev/geenius-storybook.git"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./surface": {
+      "types": "./dist/surface.d.ts",
+      "import": "./dist/surface.js"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "import": "./dist/react.js"
+    },
+    "./solidjs": {
+      "types": "./dist/solidjs.d.ts",
+      "import": "./dist/solidjs.js"
+    },
+    "./types": {
+      "types": "./dist/types.d.ts",
+      "import": "./dist/types.js"
+    },
+    "./utils": {
+      "types": "./dist/utils.d.ts",
+      "import": "./dist/utils.js"
+    },
+    "./vite": {
+      "types": "./dist/vite.d.ts",
+      "import": "./dist/vite.js"
+    },
+    "./styles": "./dist/styles.css",
+    "./theme": "./dist/theme.css",
+    "./html": "./dist/index.html"
+  },
+  "scripts": {
+    "changeset": "changeset",
+    "build": "tsup && pnpm build:assets",
+    "build:assets": "cp src/styles.css dist/styles.css && cp src/theme.css dist/theme.css && cp src/index.html dist/index.html",
+    "clean": "rm -rf dist",
+    "dev": "tsup --watch",
+    "lint": "publint",
+    "lint:pub": "publint",
+    "type-check": "tsc --noEmit",
+    "test:unit": "vitest run --passWithNoTests",
+    "test:exports": "vitest run tests/exports.test.ts",
+    "test:types": "npm_config_cache=/tmp/.npm-cache attw --pack . --ignore-rules cjs-resolves-to-esm no-resolution",
+    "test": "pnpm build && pnpm test:unit && pnpm test:exports && pnpm test:types",
+    "format": "prettier --write \"src/**/*.{ts,css,html}\"",
+    "prepublishOnly": "pnpm build"
+  },
+  "dependencies": {},
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0",
+    "solid-js": "^1.8.0 || ^1.9.0",
+    "vite": ">=5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "solid-js": {
+      "optional": true
+    },
+    "vite": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "^0.17.3",
+    "@changesets/cli": "^2.29.4",
+    "@types/react": "^19.2.2",
+    "prettier": "^3.5.3",
+    "react": "^19.2.0",
+    "solid-js": "^1.9.9",
+    "publint": "^0.3.12",
+    "tsup": "^8.5.0",
+    "typescript": "^5.8.3",
+    "vite": "^6.3.4",
+    "vitest": "^3.1.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}