@lucasvu/scope-ui 0.0.8 → 0.1.1

package/bin/scope-ui-init.mjs

@@ -6,6 +6,44 @@ import process from 'node:process'
 
 const PACKAGE_NAME = '@lucasvu/scope-ui'
 const DEFAULT_THEME_PRESET = 'ocean'
+const DEFAULT_LAYOUT_FILE = 'src/layout-presets/workspace-admin-v1.ts'
+
+const LAYOUT_PRESET = {
+  id: 'workspace-admin-v1',
+  label: 'Workspace Admin v1',
+  description:
+    'Shared admin shell with a dark sidebar, gradient topbar, soft intro card, optional segmented tabs, and card-based content blocks inspired by the Campaigns screen.',
+  recommendedFor: [
+    'Admin workspaces',
+    'Operations dashboards',
+    'CRUD-heavy backoffice screens that should share one shell',
+  ],
+  shellRecipe: [
+    'Dark left sidebar with icon + label navigation and one active item',
+    'Gradient workspace topbar with workspace label on the left and timezone/user slots on the right',
+    'Large page intro card with breadcrumb, title, and optional subtitle',
+    'Optional segmented tabs row directly under the intro card',
+    'Toolbar card with search/filters on the left and actions on the right',
+    'Main body rendered as one or more content cards instead of a flat page',
+  ],
+  requiredFields: [
+    'layoutPreset',
+    'workspaceLabel',
+    'pageKind',
+    'routeUrl',
+    'sidebarItems',
+    'activeSidebarItemId',
+    'pageTitle',
+  ],
+  askBeforeCoding: [
+    'What workspace label should appear in the topbar?',
+    'What timezone or top-right meta label should appear beside the user badge?',
+    'What sidebar items exist and which one is active on this screen?',
+    'Does this screen need segmented tabs? If yes, what are the tab labels and which tab is active?',
+    'What search placeholder, filters, and primary action belong in the toolbar card?',
+    'What columns, fields, or summary blocks should be rendered in the page body?',
+  ],
+}
 
 const THEME_PRESETS = {
   ocean: {
@@ -216,6 +254,7 @@ function parseArgs(argv) {
     force: false,
     agentsFile: 'AGENTS.md',
     themeFile: 'src/styles/ui-theme.css',
+    layoutFile: DEFAULT_LAYOUT_FILE,
     theme: DEFAULT_THEME_PRESET,
     listThemes: false,
   }
@@ -248,6 +287,16 @@ function parseArgs(argv) {
       continue
     }
 
+    if (arg === '--layout-file') {
+      const value = argv[index + 1]
+      if (!value || value.startsWith('--')) {
+        exitWithMissingValue('--layout-file')
+      }
+      args.layoutFile = value
+      index += 1
+      continue
+    }
+
     if (arg === '--theme') {
       const value = argv[index + 1]
       if (!value || value.startsWith('--')) {
@@ -288,12 +337,13 @@ Usage:
     Optional: inspect approved presets before choosing one.
 
   npx scope-ui-init --theme forest --force
-  npx scope-ui-init --agents-file AGENTS.md --theme-file src/styles/ui-theme.css
+  npx scope-ui-init --agents-file AGENTS.md --theme-file src/styles/ui-theme.css --layout-file ${DEFAULT_LAYOUT_FILE}
 
 Options:
   --force        overwrite existing files
   --agents-file  target path for the generated AGENTS.md file
   --theme-file   target path for the generated theme override file
+  --layout-file  target path for the generated layout preset file
   --theme        theme preset id (${Object.keys(THEME_PRESETS).join(', ')})
   --list-themes  show the approved preset list
   --help, -h     show this help
@@ -333,38 +383,100 @@ function renderTokenBlock(tokens) {
     .join('\n')
 }
 
-function createAgentsTemplate({ themeFile, themePreset }) {
+function renderMarkdownList(items) {
+  return items.map((item) => `- ${item}`).join('\n')
+}
+
+function createAgentsTemplate({ themeFile, layoutFile, themePreset, layoutPreset }) {
   return `# Agent Rules
 
 This repo uses \`${PACKAGE_NAME}\` as the default UI library.
+Use \`${PACKAGE_NAME}\` for React components and \`${PACKAGE_NAME}/core\` for framework-agnostic theme/runtime contracts.
 This repo is locked to the \`${themePreset.label}\` theme preset (\`${themePreset.id}\`).
+This repo uses the \`${layoutPreset.label}\` shell preset (\`${layoutPreset.id}\`) as the shared layout baseline.
 
 Primary references:
 - \`node_modules/${PACKAGE_NAME}/README.md\`
 - \`node_modules/${PACKAGE_NAME}/AI_SETUP.md\`
-- \`uiScreenBlueprint\` and \`uiAiManifest\` from \`${PACKAGE_NAME}\`
+- \`uiScreenBlueprint\`, \`uiAiManifest\`, and \`uiThemeLayerAssets\` from \`${PACKAGE_NAME}/core\`
 - \`${themeFile}\`
+- \`${layoutFile}\`
 
 Theme preset summary:
 - ${themePreset.description}
 - Recommended for: ${themePreset.recommendedFor.join(', ')}
 
+Layout preset summary:
+${renderMarkdownList(layoutPreset.shellRecipe)}
+
+## Workspace Base
+
+For Vite + micro frontend repos, keep this structure stable:
+
+- \`${PACKAGE_NAME}\` owns the React component surface
+- \`${PACKAGE_NAME}/core\` owns theme contracts, bundled theme layers, color-mode runtime, and framework-agnostic contracts
+- \`apps/shell\` owns the shared app shell, top-level routing, remote mounts, and theme imports
+- \`apps/*-mfe\` owns page-level business screens and feature routes
+
+If the repo still has a \`packages/shared\` folder, keep it for business utils or internal loaders, not for the primary theme runtime.
+
+Recommended folders:
+
+- shell: \`src/app\`, \`src/layouts\`, \`src/routes\`, \`src/remotes\`, \`src/styles/ui-theme.css\`
+- remote: \`src/features\`, \`src/pages\`, \`src/routes\`, \`src/services\`, \`src/styles/index.css\`
+
+Theme layers:
+
+1. Import \`${PACKAGE_NAME}/styles.css\` first.
+2. If the repo wants a bundled shell/theme layer, import one from \`${PACKAGE_NAME}/themes/*\` next.
+3. Import \`${themeFile}\` after the bundled theme layer.
+4. Keep app-specific overrides thin and token-based.
+
+If the bundled theme layer is client-theme-scoped, set \`data-client-theme\` with \`applyDocumentClientTheme(...)\`.
+
 ## Required Flow
 
 When asked to build or edit a screen, follow these steps in order:
 
-1. Read \`${themeFile}\`, \`node_modules/${PACKAGE_NAME}/README.md\`, \`node_modules/${PACKAGE_NAME}/AI_SETUP.md\`, and the exported \`uiScreenBlueprint\` contract before generating UI.
-2. Fill the screen brief first. If route url, sidebar items, active sidebar item, title, actions, filters, fields, or columns are missing, ask for them or leave clear TODO placeholders instead of inventing them.
-3. Verify the app entry imports \`${PACKAGE_NAME}/styles.css\` first and the project theme file right after it.
-4. Identify the page kind (\`list | form | detail | dashboard\`), then map each block to canonical components from \`uiAiManifest\` before writing JSX.
-5. Build the shell in this exact order: \`Sidebar\` -> \`Breadcrumb\` -> \`PageTitle\` -> top actions -> page body cards/grids.
-6. For list pages, build filters first and then the \`DataTable\`. For form pages, build section cards and fields. For detail pages, build summary cards and related tables. For dashboard pages, build stat cards and then supporting cards/tables.
-7. Keep all colors, radius, surface, and shadow decisions inside \`${themeFile}\`. If the preset is insufficient, update tokens there instead of styling one page ad hoc.
-8. Before finishing, run the output checklist in this file.
+1. Read \`${themeFile}\`, \`${layoutFile}\`, \`node_modules/${PACKAGE_NAME}/README.md\`, \`node_modules/${PACKAGE_NAME}/AI_SETUP.md\`, and the exported \`uiScreenBlueprint\` contract before generating UI.
+2. If the task touches app bootstrap, shell setup, or micro frontend structure, scaffold the repo around the workspace base above before writing page JSX.
+3. Fill the shell brief and screen brief first. If a required field is missing, stop and ask for that exact value before writing JSX. Only leave TODO placeholders when the user explicitly asks for an incomplete scaffold.
+4. Verify the app entry imports \`${PACKAGE_NAME}/styles.css\` first, then any bundled theme layer from \`${PACKAGE_NAME}/themes/*\`, then \`${themeFile}\`.
+5. Treat \`${layoutFile}\` as the source of truth for the app shell. Keep the dark sidebar, gradient topbar, intro card, and card-based body structure aligned with that preset unless the user explicitly asks for a different shell.
+6. Keep the shell in the host app. Do not let a remote rebuild its own global shell unless the task explicitly asks for a standalone shell.
+7. Identify the page kind (\`list | form | detail | dashboard\`), then map each block to canonical components from \`uiAiManifest\` before writing JSX.
+8. Build the shell in this exact order: \`Sidebar\` -> workspace topbar -> intro card (\`Breadcrumb\` + \`PageTitle\`) -> optional segmented tabs -> toolbar card -> page body cards/grids.
+9. For list pages, build the toolbar card first and then the \`DataTable\`. For form pages, keep the same shell and swap the body into section cards and a bottom action row. For detail pages, keep the shell and render summary/detail cards plus related tables. For dashboard pages, keep the shell and render stat cards plus supporting cards/tables.
+10. If \`${layoutFile}\` says a slot is optional, omit it cleanly when the brief does not request it. Do not invent tabs, workspace labels, filters, or toolbar actions.
+11. Keep all colors, radius, surface, and shadow decisions inside \`${themeFile}\`. If the preset is insufficient, update tokens there instead of styling one page ad hoc.
+12. Before finishing, run the output checklist in this file.
+
+## Ask For Missing Input
+
+If any of these are missing, ask the user directly before writing JSX:
+
+${renderMarkdownList(layoutPreset.askBeforeCoding)}
+
+## Shell Brief
+
+Complete this shell brief before writing JSX:
+
+\`\`\`yaml
+layoutPreset: ${layoutPreset.id}
+workspaceLabel:
+timezoneLabel:
+userBadgeLabel:
+pageTabs:
+  - value:
+    label:
+activePageTab:
+searchPlaceholder:
+toolbarNote:
+\`\`\`
 
 ## Screen Brief
 
-Complete this brief before writing JSX:
+Complete this screen brief before writing JSX:
 
 \`\`\`yaml
 pageKind: list | form | detail | dashboard
@@ -373,6 +485,7 @@ sidebarItems:
   - id:
     title:
     href:
+    icon:
 activeSidebarItemId:
 breadcrumbs:
   - label:
@@ -421,29 +534,44 @@ emptyState:
 permissions: []
 \`\`\`
 
+## Shell Lock
+
+Keep the layout aligned with \`${layoutPreset.id}\`:
+
+${renderMarkdownList(layoutPreset.shellRecipe)}
+
 ## Page Frame Recipes
 
-- \`list\`: \`Sidebar\` -> \`Breadcrumb\` -> \`PageTitle\` -> header actions -> optional stats -> filter \`Card\` -> \`DataTable\` \`Card\`
-- \`form\`: \`Sidebar\` -> \`Breadcrumb\` -> \`PageTitle\` -> primary/cancel actions -> sectioned form \`Card\` blocks -> bottom action row
-- \`detail\`: \`Sidebar\` -> \`Breadcrumb\` -> \`PageTitle\` -> status/actions -> summary metadata \`Card\` -> detail \`Card\` blocks -> related \`DataTable\`
-- \`dashboard\`: \`Sidebar\` -> \`Breadcrumb\` -> \`PageTitle\` -> header actions -> \`Stat\` row -> filters -> insight \`Card\` blocks and \`DataTable\`
+- \`list\`: dark \`Sidebar\` -> workspace topbar -> intro card -> optional segmented tabs -> toolbar \`Card\` -> \`DataTable\` \`Card\`
+- \`form\`: dark \`Sidebar\` -> workspace topbar -> intro card -> optional segmented tabs -> top actions -> sectioned form \`Card\` blocks -> bottom action row
+- \`detail\`: dark \`Sidebar\` -> workspace topbar -> intro card -> optional segmented tabs -> status/actions -> summary metadata \`Card\` -> detail \`Card\` blocks -> related \`DataTable\`
+- \`dashboard\`: dark \`Sidebar\` -> workspace topbar -> intro card -> optional segmented tabs -> toolbar \`Card\` -> \`Stat\` row -> insight \`Card\` blocks and \`DataTable\`
 
 ## Hard Rules
 
 - import \`${PACKAGE_NAME}/styles.css\` once at the app entry
-- import the project theme override file after the package stylesheet
-- use root exports from \`${PACKAGE_NAME}\`
+- import a bundled theme layer from \`${PACKAGE_NAME}/themes/*\` after the package stylesheet when the repo chooses one
+- import the project theme override file after the bundled theme layer
+- use \`applyDocumentClientTheme\` when the chosen bundled theme layer is client-theme-scoped
+- use root exports from \`${PACKAGE_NAME}\` for React components
+- use \`${PACKAGE_NAME}/core\` for theme/runtime utilities in non-React or mixed-framework setup
 - use \`${themeFile}\` as the only source of truth for colors, radius, surfaces, and shadows
+- use \`${layoutFile}\` as the source of truth for the shell layout and shared page frame
 - keep layouts and component choices aligned with the shared preset-driven UI used across projects
+- keep the host shell responsible for sidebar, topbar, remote mount, and theme mode
+- keep remotes focused on feature routes and page business content
 - read \`uiAiManifest\` before choosing components
+- read \`uiThemeLayerAssets\` before choosing a bundled theme layer
 - read \`uiThemeContract\` before changing colors, surfaces, borders, radius, or shadows
 - keep UI token-driven and theme-driven
 
 Do not:
 - import from \`MainFe\` unless the task explicitly targets a legacy screen
 - invent a second palette or one-off brand colors outside \`${themeFile}\`
+- replace the shared dark-sidebar + gradient-topbar shell with a flat blank layout unless the user explicitly requests it
 - restyle individual pages if the preset tokens can solve it globally
 - create duplicate Button/Input/Select wrappers unless a project-specific behavior is required
+- let each remote define a different shell or a different palette
 
 ## Component Choice
 
@@ -461,13 +589,17 @@ Do not:
 
 Before finishing, confirm all of these are true:
 
-- The screen brief is complete or unresolved values are clearly marked as TODO.
-- The shell contains \`Sidebar\`, \`Breadcrumb\`, and \`PageTitle\` in the correct order.
+- The shell brief and screen brief are complete.
+- Any missing required input was explicitly asked for before coding.
+- The shell matches \`${layoutPreset.id}\` with a dark sidebar, gradient topbar, intro card, and card-based body structure.
 - The chosen components match the page kind and the brief.
 - No \`MainFe\` imports were used.
 - No hardcoded brand colors were added in page components.
 - Theme decisions live in \`${themeFile}\`, not in ad hoc JSX styling.
+- The app entry import order is package stylesheet -> bundled theme layer if present -> project theme override.
+- The shell still lives in the host app and remotes only own business screens.
 - Spacing, card structure, and actions are consistent with the shared preset.
+- The layout shell stayed stable even if the page body changed.
 `
 }
 
@@ -487,6 +619,110 @@ ${renderTokenBlock(themePreset.tokens.dark)}
 `
 }
 
+function createLayoutTemplate({ themeFile, layoutPreset }) {
+  return `/* Generated by scope-ui-init. */
+/* Layout preset: ${layoutPreset.label} (${layoutPreset.id}) */
+/* Use this file as the shared app-shell source of truth for AI/codegen. */
+
+export const uiLayoutPreset = {
+  id: '${layoutPreset.id}',
+  label: '${layoutPreset.label}',
+  description:
+    '${layoutPreset.description}',
+  themeSource: '${themeFile}',
+  recommendedFor: [
+${layoutPreset.recommendedFor.map((item) => `    '${item}',`).join('\n')}
+  ],
+  shellRecipe: [
+${layoutPreset.shellRecipe.map((item) => `    '${item}',`).join('\n')}
+  ],
+  requiredFields: [
+${layoutPreset.requiredFields.map((item) => `    '${item}',`).join('\n')}
+  ],
+  askBeforeCoding: [
+${layoutPreset.askBeforeCoding.map((item) => `    '${item}',`).join('\n')}
+  ],
+  workspaceStructure: {
+    packageUi: ['components', 'theme contracts', 'bundled theme layers', 'color-mode runtime'],
+    shellApp: ['src/app', 'src/layouts', 'src/routes', 'src/remotes', 'src/styles/ui-theme.css'],
+    remoteApp: ['src/features', 'src/pages', 'src/routes', 'src/services', 'src/styles/index.css'],
+  },
+  themeLayers: [
+    '${PACKAGE_NAME}/styles.css',
+    '${PACKAGE_NAME}/themes/theme-ui-new-main-fe.css (optional bundled package layer)',
+    '${themeFile}',
+  ],
+  setupSteps: [
+    'Import the package stylesheet once at the host app entry.',
+    'If the app wants a bundled package theme layer, import it after the package stylesheet.',
+    'Import the project themeSource after the bundled theme layer.',
+    'If the chosen theme layer is client-theme-scoped, set data-client-theme at the document root.',
+    'Initialize color mode at the host app entry and let the host own shell/theme concerns.',
+    'Keep remotes focused on feature routes and business screens instead of rebuilding the global shell.',
+  ],
+  shell: {
+    sidebar: {
+      tone: 'dark',
+      width: '240px',
+      content: ['workspace badge', 'icon + label navigation', 'active state'],
+    },
+    topbar: {
+      background: 'theme gradient from --primary-grad-from to --primary-grad-to',
+      leftSlot: 'workspaceLabel',
+      rightSlots: ['timezoneLabel', 'userBadgeLabel'],
+    },
+    introCard: {
+      content: ['breadcrumbs', 'pageTitle', 'pageSubtitle'],
+      surface: 'soft elevated card',
+    },
+    pageTabs: {
+      optional: true,
+      style: 'segmented pills',
+      fields: ['pageTabs', 'activePageTab'],
+    },
+    toolbarCard: {
+      optional: true,
+      leftSlots: ['searchPlaceholder', 'filters'],
+      rightSlots: ['secondaryActions', 'primaryAction'],
+    },
+  },
+  pageBodies: {
+    list: ['toolbar card', 'DataTable card', 'rowActions', 'emptyState'],
+    form: ['sectioned form cards', 'fields', 'bottom action row'],
+    detail: ['summary metadata card', 'detailSections', 'related tables'],
+    dashboard: ['summaryStats', 'filters', 'insight cards', 'DataTable'],
+  },
+  hardRules: [
+    'Keep the dark sidebar and gradient topbar shell stable across screens.',
+    'Do not replace the intro card with a bare page title row.',
+    'Use the shared theme tokens from the themeSource file for color, border, surface, and shadow decisions.',
+    'Import theme layers in this order: package stylesheet, bundled package theme layer when present, then themeSource.',
+    'Keep the host app responsible for the global shell and keep remotes page-scoped.',
+    'Only omit tabs or toolbar sections when the brief explicitly leaves them out.',
+    'Ask for missing required fields before generating JSX instead of guessing from the screenshot.',
+  ],
+  exampleBrief: {
+    layoutPreset: '${layoutPreset.id}',
+    workspaceLabel: 'Workspace',
+    timezoneLabel: 'UTC+07:00',
+    userBadgeLabel: 'L',
+    pageKind: 'list',
+    routeUrl: '/campaigns/new',
+    activeSidebarItemId: 'campaigns',
+    pageTabs: [
+      { value: 'overview', label: 'Overview' },
+      { value: 'coupons', label: 'Coupons' },
+      { value: 'redemption', label: 'Redemption' },
+    ],
+    activePageTab: 'coupons',
+    searchPlaceholder: 'Search by coupon code',
+  },
+} as const
+
+export type UiLayoutPreset = typeof uiLayoutPreset
+`
+}
+
 function writeFile(targetPath, content, force) {
   const absolutePath = resolve(process.cwd(), targetPath)
   const alreadyExists = existsSync(absolutePath)
@@ -511,7 +747,12 @@ const themePreset = resolveThemePreset(options.theme)
 
 const agentsResult = writeFile(
   options.agentsFile,
-  createAgentsTemplate({ themeFile: options.themeFile, themePreset }),
+  createAgentsTemplate({
+    themeFile: options.themeFile,
+    layoutFile: options.layoutFile,
+    themePreset,
+    layoutPreset: LAYOUT_PRESET,
+  }),
   options.force,
 )
 
@@ -521,13 +762,23 @@ const themeResult = writeFile(
   options.force,
 )
 
+const layoutResult = writeFile(
+  options.layoutFile,
+  createLayoutTemplate({ themeFile: options.themeFile, layoutPreset: LAYOUT_PRESET }),
+  options.force,
+)
+
 console.log(`Initialized ${PACKAGE_NAME}`)
 console.log(`- theme preset: ${themePreset.label} (${themePreset.id})`)
+console.log(`- layout preset: ${LAYOUT_PRESET.label} (${LAYOUT_PRESET.id})`)
 console.log(`- ${agentsResult.path}: ${agentsResult.status}`)
 console.log(`- ${themeResult.path}: ${themeResult.status}`)
+console.log(`- ${layoutResult.path}: ${layoutResult.status}`)
 console.log('')
 console.log('Next steps:')
 console.log(`1. Import \`${PACKAGE_NAME}/styles.css\` once at your app entry.`)
-console.log(`2. Import \`${options.themeFile}\` right after the package stylesheet.`)
-console.log(`3. Let your agent read \`${options.agentsFile}\` before generating UI.`)
-console.log(`4. Re-run this command with \`--theme <preset> --force\` if you want another approved preset.`)
+console.log(`2. If you want a bundled package theme layer, import one from \`${PACKAGE_NAME}/themes/*\` right after the package stylesheet.`)
+console.log(`3. Import \`${options.themeFile}\` after the bundled theme layer.`)
+console.log(`4. Let your agent read \`${options.agentsFile}\` and \`${options.layoutFile}\` before generating UI.`)
+console.log('5. Keep the host app responsible for the global shell and keep remotes page-scoped.')
+console.log(`6. Re-run this command with \`--theme <preset> --force\` if you want another approved preset.`)