@lucasvu/scope-ui 0.0.4 → 0.0.6

package/dist/index.cjs

@@ -6646,6 +6646,8 @@ var uiAiManifest = {
   styleImport: "@lucasvu/scope-ui/styles.css",
   rules: [
     "Import the stylesheet once at the app entry before rendering any component.",
+    "If the project declares an approved theme preset in AGENTS.md or ui-theme.css, stay inside that preset and do not invent a second palette.",
+    "Collect the screen brief first: route url, sidebar items, active sidebar item, page title, actions, and the page-specific content schema.",
     "Prefer the canonical component for each intent instead of mixing legacy MainFe components.",
     "Use Input/Textarea/Select label props directly for simple fields; use Field only to wrap custom controls or grouped content.",
     "Use Select for small fixed option lists, SearchableSelect for larger local lists, Combobox for type-and-pick flows, and AsyncCombobox for remote search.",
@@ -6861,7 +6863,420 @@ var uiAiManifest = {
   ]
 };
 
+// src/screen-blueprint.ts
+var uiScreenBriefFields = [
+  {
+    id: "pageKind",
+    label: "Page kind",
+    description: "Choose the base recipe for the screen.",
+    required: true,
+    appliesTo: ["all"],
+    example: "list"
+  },
+  {
+    id: "routeUrl",
+    label: "Route URL",
+    description: "Final route for the screen or feature entry.",
+    required: true,
+    appliesTo: ["all"],
+    example: "/admin/users"
+  },
+  {
+    id: "sidebarItems",
+    label: "Sidebar items",
+    description: "Sidebar entries with at least id, title, and href so the shell stays consistent.",
+    required: true,
+    appliesTo: ["all"],
+    example: '[{ id: "users", title: "Users", href: "/admin/users" }]'
+  },
+  {
+    id: "activeSidebarItemId",
+    label: "Active sidebar item id",
+    description: "The sidebar item that should appear active on this screen.",
+    required: true,
+    appliesTo: ["all"],
+    example: "users"
+  },
+  {
+    id: "breadcrumbs",
+    label: "Breadcrumbs",
+    description: "Ordered breadcrumb items for the page header.",
+    required: false,
+    appliesTo: ["all"],
+    example: '[{ label: "Admin", href: "/admin" }, { label: "Users", current: true }]'
+  },
+  {
+    id: "pageTitle",
+    label: "Page title",
+    description: "Main page heading shown in the content header.",
+    required: true,
+    appliesTo: ["all"],
+    example: "Users"
+  },
+  {
+    id: "pageSubtitle",
+    label: "Page subtitle",
+    description: "Short supporting text under the title.",
+    required: false,
+    appliesTo: ["all"],
+    example: "Manage internal user accounts and permissions."
+  },
+  {
+    id: "primaryAction",
+    label: "Primary action",
+    description: "The highest-emphasis action shown in the page header.",
+    required: false,
+    appliesTo: ["all"],
+    example: '{ label: "Create user", href: "/admin/users/create" }'
+  },
+  {
+    id: "secondaryActions",
+    label: "Secondary actions",
+    description: "Additional header actions such as export, refresh, or cancel.",
+    required: false,
+    appliesTo: ["all"],
+    example: '[{ label: "Export" }, { label: "Refresh" }]'
+  },
+  {
+    id: "summaryStats",
+    label: "Summary stats",
+    description: "Top-line numbers for dashboard or overview screens.",
+    required: false,
+    appliesTo: ["dashboard", "detail"],
+    example: '[{ label: "Active users", value: "1,204", trend: "up", delta: "+12%" }]'
+  },
+  {
+    id: "filters",
+    label: "Filters",
+    description: "Filter bar controls shown above list or dashboard content.",
+    required: false,
+    appliesTo: ["list", "dashboard"],
+    example: '[{ type: "search", label: "Search user" }, { type: "select", label: "Role" }]'
+  },
+  {
+    id: "tableColumns",
+    label: "Table columns",
+    description: "Columns for a list table, including label and render intent.",
+    required: false,
+    appliesTo: ["list", "detail", "dashboard"],
+    example: '[{ key: "name", title: "Name" }, { key: "role", title: "Role" }]'
+  },
+  {
+    id: "rowActions",
+    label: "Row actions",
+    description: "Per-row actions for table screens.",
+    required: false,
+    appliesTo: ["list", "detail"],
+    example: '[{ label: "Edit" }, { label: "Reset password" }]'
+  },
+  {
+    id: "formSections",
+    label: "Form sections",
+    description: "Grouped form sections and the fields inside each section.",
+    required: false,
+    appliesTo: ["form"],
+    example: '[{ title: "Basic info", fields: ["name", "email", "role"] }]'
+  },
+  {
+    id: "fields",
+    label: "Fields",
+    description: "Detailed field list with type, label, required state, and helper text.",
+    required: false,
+    appliesTo: ["form", "detail"],
+    example: '[{ name: "email", type: "input", label: "Email", required: true }]'
+  },
+  {
+    id: "detailSections",
+    label: "Detail sections",
+    description: "Cards or sections for detail pages such as profile, activity, permissions, or related records.",
+    required: false,
+    appliesTo: ["detail"],
+    example: '[{ title: "Profile" }, { title: "Recent activity" }]'
+  },
+  {
+    id: "emptyState",
+    label: "Empty state",
+    description: "Fallback title, description, and action when there is no data.",
+    required: false,
+    appliesTo: ["list", "dashboard", "detail"],
+    example: '{ title: "No users yet", description: "Create the first user to get started." }'
+  },
+  {
+    id: "permissions",
+    label: "Permissions",
+    description: "Permission keys that affect sidebar visibility or action availability.",
+    required: false,
+    appliesTo: ["all"],
+    example: '["user.read", "user.write"]'
+  }
+];
+var uiScreenBlueprint = {
+  pageKinds: [
+    {
+      id: "list",
+      label: "List page",
+      frame: [
+        "Sidebar shell",
+        "Breadcrumb",
+        "PageTitle with actions",
+        "Optional stats",
+        "Filter card",
+        "DataTable card"
+      ]
+    },
+    {
+      id: "form",
+      label: "Form page",
+      frame: [
+        "Sidebar shell",
+        "Breadcrumb",
+        "PageTitle with primary and cancel actions",
+        "Sectioned form cards",
+        "Bottom action row"
+      ]
+    },
+    {
+      id: "detail",
+      label: "Detail page",
+      frame: [
+        "Sidebar shell",
+        "Breadcrumb",
+        "PageTitle with status/actions",
+        "Summary stats or metadata card",
+        "Detail cards and related tables"
+      ]
+    },
+    {
+      id: "dashboard",
+      label: "Dashboard page",
+      frame: [
+        "Sidebar shell",
+        "Breadcrumb",
+        "PageTitle with actions",
+        "Stat cards row",
+        "Filters",
+        "Main insight cards and tables"
+      ]
+    }
+  ],
+  workflow: [
+    "Collect the screen brief before coding. Do not invent sidebar items, route urls, filters, fields, or table columns if the brief is missing.",
+    "Use Sidebar plus Breadcrumb and PageTitle to lock the shell before building the page body.",
+    "Choose only canonical root exports from @lucasvu/scope-ui.",
+    "Use Card and ui-grid utilities to create the frame first, then place controls and data components inside.",
+    "Keep all palette, radius, surface, and shadow decisions in the shared ui-theme.css preset file.",
+    "End with a consistency check against the selected preset and the screen brief."
+  ],
+  briefFields: uiScreenBriefFields
+};
+
 // src/theme-contract.ts
+var uiThemePresets = [
+  {
+    id: "ocean",
+    label: "Ocean Glass",
+    description: "Blue-cyan preset with clean glass surfaces. Matches the current default visual language.",
+    recommendedFor: [
+      "Admin dashboards",
+      "SaaS CRUD screens",
+      "Projects that want the existing package look"
+    ],
+    tokens: {
+      light: {
+        "--tw-background": "0 0% 100%",
+        "--tw-foreground": "222.2 47.4% 11.2%",
+        "--tw-primary": "221.2 83.2% 53.3%",
+        "--tw-accent": "199 89% 48%",
+        "--tw-success": "142.1 76.2% 36.3%",
+        "--tw-destructive": "0 84.2% 60.2%",
+        "--tw-border": "214.3 31.8% 91.4%",
+        "--radius": "0.75rem",
+        "--surface": "rgba(255, 255, 255, 0.92)",
+        "--surface-strong": "rgba(241, 245, 249, 0.96)",
+        "--grey": "rgba(248, 250, 252, 0.96)",
+        "--grey-strong": "rgba(241, 245, 249, 0.98)",
+        "--shadow-sm": "0 10px 28px -18px rgba(15, 23, 42, 0.22)",
+        "--shadow": "0 24px 60px -28px rgba(15, 23, 42, 0.3)",
+        "--primary-grad-from": "199 89% 48%",
+        "--primary-grad-to": "221.2 83.2% 53.3%"
+      },
+      dark: {
+        "--tw-background": "222.2 84% 4.9%",
+        "--tw-foreground": "210 40% 98%",
+        "--tw-primary": "217.2 91.2% 59.8%",
+        "--tw-accent": "199 89% 48%",
+        "--tw-success": "142.1 70.6% 45.3%",
+        "--tw-destructive": "0 62.8% 30.6%",
+        "--tw-border": "217.2 32.6% 17.5%",
+        "--radius": "0.75rem",
+        "--surface": "rgba(15, 23, 42, 0.78)",
+        "--surface-strong": "rgba(30, 41, 59, 0.92)",
+        "--grey": "rgba(30, 41, 59, 0.88)",
+        "--grey-strong": "rgba(51, 65, 85, 0.92)",
+        "--shadow-sm": "0 16px 32px -18px rgba(2, 6, 23, 0.48)",
+        "--shadow": "0 28px 80px -32px rgba(2, 6, 23, 0.7)",
+        "--primary-grad-from": "198.6 88.7% 48.4%",
+        "--primary-grad-to": "221.2 83.2% 53.3%"
+      }
+    }
+  },
+  {
+    id: "sunset",
+    label: "Sunset Ember",
+    description: "Warm orange-coral preset with softer cream surfaces for branded landing or growth products.",
+    recommendedFor: [
+      "Growth products",
+      "Commerce backoffices",
+      "Projects that want a warmer visual tone"
+    ],
+    tokens: {
+      light: {
+        "--tw-background": "30 100% 98%",
+        "--tw-foreground": "20 24% 14%",
+        "--tw-primary": "14 90% 56%",
+        "--tw-accent": "29 100% 58%",
+        "--tw-success": "145 63% 38%",
+        "--tw-destructive": "0 78% 58%",
+        "--tw-border": "24 45% 89%",
+        "--radius": "0.85rem",
+        "--surface": "rgba(255, 247, 240, 0.92)",
+        "--surface-strong": "rgba(255, 237, 223, 0.96)",
+        "--grey": "rgba(255, 243, 231, 0.96)",
+        "--grey-strong": "rgba(255, 232, 214, 0.98)",
+        "--shadow-sm": "0 12px 30px -18px rgba(194, 65, 12, 0.18)",
+        "--shadow": "0 28px 64px -30px rgba(154, 52, 18, 0.24)",
+        "--primary-grad-from": "29 100% 58%",
+        "--primary-grad-to": "14 90% 56%"
+      },
+      dark: {
+        "--tw-background": "20 24% 8%",
+        "--tw-foreground": "40 33% 96%",
+        "--tw-primary": "18 100% 62%",
+        "--tw-accent": "35 100% 58%",
+        "--tw-success": "145 60% 47%",
+        "--tw-destructive": "0 73% 52%",
+        "--tw-border": "18 24% 22%",
+        "--radius": "0.85rem",
+        "--surface": "rgba(41, 24, 18, 0.84)",
+        "--surface-strong": "rgba(59, 34, 24, 0.9)",
+        "--grey": "rgba(70, 42, 29, 0.88)",
+        "--grey-strong": "rgba(92, 54, 38, 0.9)",
+        "--shadow-sm": "0 18px 36px -20px rgba(67, 20, 7, 0.48)",
+        "--shadow": "0 30px 84px -34px rgba(67, 20, 7, 0.62)",
+        "--primary-grad-from": "35 100% 58%",
+        "--primary-grad-to": "18 100% 62%"
+      }
+    }
+  },
+  {
+    id: "forest",
+    label: "Forest Mist",
+    description: "Emerald-teal preset with soft botanical surfaces for calmer productivity products.",
+    recommendedFor: [
+      "Operations tools",
+      "Internal platforms",
+      "Products that want a calmer green tone"
+    ],
+    tokens: {
+      light: {
+        "--tw-background": "138 40% 98%",
+        "--tw-foreground": "160 25% 14%",
+        "--tw-primary": "158 64% 40%",
+        "--tw-accent": "173 58% 44%",
+        "--tw-success": "145 63% 36%",
+        "--tw-destructive": "0 78% 58%",
+        "--tw-border": "143 21% 88%",
+        "--radius": "0.8rem",
+        "--surface": "rgba(245, 252, 249, 0.92)",
+        "--surface-strong": "rgba(232, 245, 239, 0.96)",
+        "--grey": "rgba(240, 248, 244, 0.96)",
+        "--grey-strong": "rgba(225, 240, 232, 0.98)",
+        "--shadow-sm": "0 12px 28px -18px rgba(5, 86, 66, 0.18)",
+        "--shadow": "0 26px 62px -30px rgba(6, 78, 59, 0.24)",
+        "--primary-grad-from": "173 58% 44%",
+        "--primary-grad-to": "158 64% 40%"
+      },
+      dark: {
+        "--tw-background": "164 35% 8%",
+        "--tw-foreground": "144 35% 96%",
+        "--tw-primary": "160 70% 46%",
+        "--tw-accent": "174 72% 45%",
+        "--tw-success": "145 68% 46%",
+        "--tw-destructive": "0 70% 52%",
+        "--tw-border": "160 20% 20%",
+        "--radius": "0.8rem",
+        "--surface": "rgba(16, 36, 31, 0.84)",
+        "--surface-strong": "rgba(21, 51, 44, 0.9)",
+        "--grey": "rgba(24, 61, 52, 0.88)",
+        "--grey-strong": "rgba(31, 77, 65, 0.9)",
+        "--shadow-sm": "0 18px 34px -20px rgba(1, 44, 34, 0.48)",
+        "--shadow": "0 30px 82px -34px rgba(1, 44, 34, 0.6)",
+        "--primary-grad-from": "174 72% 45%",
+        "--primary-grad-to": "160 70% 46%"
+      }
+    }
+  },
+  {
+    id: "graphite",
+    label: "Graphite Pulse",
+    description: "Neutral slate preset with restrained blue accents for products that need a steadier enterprise tone.",
+    recommendedFor: [
+      "Enterprise admin panels",
+      "B2B internal tools",
+      "Projects that want a more neutral interface"
+    ],
+    tokens: {
+      light: {
+        "--tw-background": "220 18% 97%",
+        "--tw-foreground": "222 24% 14%",
+        "--tw-primary": "221 24% 32%",
+        "--tw-accent": "198 83% 44%",
+        "--tw-success": "160 56% 38%",
+        "--tw-destructive": "0 72% 54%",
+        "--tw-border": "218 17% 86%",
+        "--radius": "0.7rem",
+        "--surface": "rgba(248, 250, 252, 0.94)",
+        "--surface-strong": "rgba(226, 232, 240, 0.96)",
+        "--grey": "rgba(241, 245, 249, 0.98)",
+        "--grey-strong": "rgba(226, 232, 240, 0.99)",
+        "--shadow-sm": "0 12px 30px -20px rgba(15, 23, 42, 0.18)",
+        "--shadow": "0 28px 66px -30px rgba(15, 23, 42, 0.24)",
+        "--primary-grad-from": "198 83% 44%",
+        "--primary-grad-to": "221 24% 32%"
+      },
+      dark: {
+        "--tw-background": "222 32% 8%",
+        "--tw-foreground": "210 25% 96%",
+        "--tw-primary": "210 24% 82%",
+        "--tw-accent": "192 92% 52%",
+        "--tw-success": "158 64% 45%",
+        "--tw-destructive": "0 72% 56%",
+        "--tw-border": "217 19% 24%",
+        "--radius": "0.7rem",
+        "--surface": "rgba(15, 23, 42, 0.82)",
+        "--surface-strong": "rgba(30, 41, 59, 0.92)",
+        "--grey": "rgba(30, 41, 59, 0.9)",
+        "--grey-strong": "rgba(51, 65, 85, 0.92)",
+        "--shadow-sm": "0 18px 38px -22px rgba(2, 6, 23, 0.48)",
+        "--shadow": "0 32px 88px -34px rgba(2, 6, 23, 0.68)",
+        "--primary-grad-from": "192 92% 52%",
+        "--primary-grad-to": "210 24% 82%"
+      }
+    }
+  }
+];
+var uiDefaultThemePreset = uiThemePresets[0];
+function createThemePresetCssExample(themePreset) {
+  const renderBlock = (tokens) => Object.entries(tokens).map(([token, value]) => `  ${token}: ${value};`).join("\n");
+  return `:root {
+${renderBlock(themePreset.tokens.light)}
+}
+
+.dark,
+[data-ui-theme='dark'] {
+${renderBlock(themePreset.tokens.dark)}
+}`;
+}
 var uiThemeContract = {
   packageName: "@lucasvu/scope-ui",
   importOrder: [
@@ -6873,8 +7288,11 @@ var uiThemeContract = {
     dark: [".dark", "[data-ui-theme='dark']"]
   },
   overrideFile: "src/styles/ui-theme.css",
+  defaultPreset: uiDefaultThemePreset.id,
+  presets: uiThemePresets,
   rules: [
     "Import the package stylesheet before your project theme override stylesheet.",
+    "Choose one approved preset and keep the entire project on that preset instead of mixing palettes page by page.",
     "Override tokens in one shared theme file instead of scattering colors across components.",
     "Use :root for the default light theme and .dark or [data-ui-theme='dark'] for dark theme.",
     "Only override tokens declared here. Do not patch component internals unless you are extending the library.",
@@ -6886,7 +7304,7 @@ var uiThemeContract = {
       description: "Base app background in HSL triplet format.",
       defaultLight: "0 0% 100%",
       defaultDark: "222.2 84% 4.9%",
-      usedBy: ["Input", "Select", "Card", "Tabs", "global surface"]
+      usedBy: ["body background", "Input fallback", "page background"]
     },
     {
       name: "--tw-foreground",
@@ -6930,6 +7348,13 @@ var uiThemeContract = {
       defaultDark: "217.2 32.6% 17.5%",
       usedBy: ["Input", "Select", "Card", "DataTable"]
     },
+    {
+      name: "--radius",
+      description: "Shared component radius.",
+      defaultLight: "0.75rem",
+      defaultDark: "0.75rem",
+      usedBy: ["Button", "Input", "Card", "Tabs"]
+    },
     {
       name: "--surface",
       description: "Default surface background as a CSS color.",
@@ -6958,6 +7383,20 @@ var uiThemeContract = {
       defaultDark: "rgba(51, 65, 85, 0.92)",
       usedBy: ["DataTable row hover"]
     },
+    {
+      name: "--shadow-sm",
+      description: "Small elevation shadow.",
+      defaultLight: "0 10px 28px -18px rgba(15, 23, 42, 0.22)",
+      defaultDark: "0 16px 32px -18px rgba(2, 6, 23, 0.48)",
+      usedBy: ["Tabs", "Pagination", "subtle elevation"]
+    },
+    {
+      name: "--shadow",
+      description: "Primary elevation shadow.",
+      defaultLight: "0 24px 60px -28px rgba(15, 23, 42, 0.3)",
+      defaultDark: "0 28px 80px -32px rgba(2, 6, 23, 0.7)",
+      usedBy: ["Card", "Button emphasis", "floating surfaces"]
+    },
     {
       name: "--text",
       description: "Generic text color alias as a CSS color.",
@@ -6994,26 +7433,15 @@ var uiThemeContract = {
       usedBy: ["Button variant create"]
     }
   ],
-  exampleCss: `:root {
-  --tw-primary: 12 88% 56%;
-  --tw-accent: 24 95% 52%;
-  --primary-grad-from: 24 95% 52%;
-  --primary-grad-to: 12 88% 56%;
-  --surface: rgba(255, 248, 240, 0.92);
-}
-
-.dark {
-  --tw-primary: 18 100% 62%;
-  --tw-accent: 35 100% 58%;
-  --surface: rgba(24, 24, 27, 0.82);
-}`
+  exampleCss: createThemePresetCssExample(uiDefaultThemePreset)
 };
 var uiProjectAiRules = [
   "Use @lucasvu/scope-ui as the default UI library.",
   "Import @lucasvu/scope-ui/styles.css once at the app entry.",
   "Import the project override theme file after the package stylesheet.",
+  "Stay inside the approved theme preset declared by the project and do not invent a second palette.",
   "Read uiAiManifest to choose the correct component by intent before coding.",
-  "Read uiThemeContract before changing colors, shadows, or theme behavior.",
+  "Read uiThemeContract before changing colors, shadows, radius, or theme behavior.",
   "Prefer root exports and avoid MainFe unless the task explicitly targets a legacy screen."
 ];
 
@@ -7074,5 +7502,9 @@ exports.defaultPermissionChecker = defaultPermissionChecker;
 exports.filterSidebarItems = filterSidebarItems;
 exports.hasActiveDescendant = hasActiveDescendant;
 exports.uiAiManifest = uiAiManifest;
+exports.uiDefaultThemePreset = uiDefaultThemePreset;
 exports.uiProjectAiRules = uiProjectAiRules;
+exports.uiScreenBlueprint = uiScreenBlueprint;
+exports.uiScreenBriefFields = uiScreenBriefFields;
 exports.uiThemeContract = uiThemeContract;
+exports.uiThemePresets = uiThemePresets;