@lucasvu/scope-ui 0.0.1 → 0.0.2

package/dist/index.js

@@ -435,6 +435,7 @@ var Button = forwardRef(
     disabled,
     startIcon,
     endIcon,
+    block = false,
     className,
     style,
     children,
@@ -447,14 +448,14 @@ var Button = forwardRef(
     const describedBy = [helperId, errorId].filter(Boolean).join(" ") || void 0;
     const content = children ?? label;
     const isDisabled = disabled || loading;
-    return /* @__PURE__ */ jsxs("div", { className: "flex flex-col gap-1", style, children: [
+    return /* @__PURE__ */ jsxs("div", { className: cn("flex flex-col gap-1", block && "w-full"), style, children: [
       /* @__PURE__ */ jsxs(
         "button",
         {
           ref,
           id: buttonId,
           type: type ?? "button",
-          className: cn(buttonVariants({ variant, size, className })),
+          className: cn(buttonVariants({ variant, size, className }), block && "w-full"),
           disabled: isDisabled,
           "aria-describedby": describedBy,
           "aria-busy": loading || void 0,
@@ -875,6 +876,94 @@ var NumericInput = forwardRef(
   }
 );
 NumericInput.displayName = "NumericInput";
+var textareaVariants = cva(
+  "flex min-h-[104px] w-full resize-y rounded-md border px-3 py-2 text-sm font-medium transition placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:cursor-not-allowed disabled:opacity-60",
+  {
+    variants: {
+      variant: {
+        default: "border-input bg-background text-foreground hover:border-border",
+        ghost: "border-transparent bg-transparent text-foreground focus-visible:border-border/60",
+        outline: "border border-border bg-transparent text-foreground"
+      },
+      size: {
+        sm: "min-h-[88px] text-sm",
+        md: "min-h-[104px] text-sm",
+        lg: "min-h-[120px] text-base"
+      }
+    },
+    defaultVariants: {
+      variant: "default",
+      size: "md"
+    }
+  }
+);
+var Textarea = forwardRef(
+  ({
+    variant = "default",
+    size = "md",
+    label,
+    helperText,
+    errorMessage,
+    loading,
+    disabled,
+    className,
+    style,
+    textareaClassName,
+    id,
+    onChange,
+    onValueChange,
+    suffix,
+    rows,
+    ...rest
+  }, ref) => {
+    const generatedId = useId();
+    const textareaId = id ?? generatedId;
+    const helperId = helperText ? `${textareaId}-helper` : void 0;
+    const errorId = errorMessage ? `${textareaId}-error` : void 0;
+    const hasRightAccessory = Boolean(suffix) || Boolean(loading);
+    return /* @__PURE__ */ jsx(
+      FieldWrapper,
+      {
+        label,
+        helperText,
+        errorMessage,
+        helperId,
+        errorId,
+        htmlFor: textareaId,
+        className,
+        style,
+        children: /* @__PURE__ */ jsxs("div", { className: "relative w-full", children: [
+          /* @__PURE__ */ jsx(
+            "textarea",
+            {
+              id: textareaId,
+              ref,
+              rows: rows ?? 4,
+              className: cn(
+                textareaVariants({ variant, size }),
+                hasRightAccessory && "pr-10",
+                textareaClassName
+              ),
+              disabled: disabled || loading,
+              "aria-invalid": Boolean(errorMessage),
+              "aria-describedby": [helperId, errorId].filter(Boolean).join(" ") || void 0,
+              onChange: (event) => {
+                onChange?.(event);
+                onValueChange?.(event.target.value);
+              },
+              ...rest
+            }
+          ),
+          hasRightAccessory ? /* @__PURE__ */ jsxs("span", { className: "pointer-events-none absolute right-3 top-3 flex items-center gap-2 text-muted-foreground", children: [
+            loading ? /* @__PURE__ */ jsx(LoadingSpinner, { size: "xs" }) : null,
+            suffix ? /* @__PURE__ */ jsx("span", { children: suffix }) : null
+          ] }) : null
+        ] })
+      }
+    );
+  }
+);
+Textarea.displayName = "Textarea";
 function Card({ className, ...props }) {
   return /* @__PURE__ */ jsx(
     "div",
@@ -1780,9 +1869,18 @@ function CheckMark() {
 function Form({ className, ...props }) {
   return /* @__PURE__ */ jsx("form", { className: cn("space-y-6", className), ...props });
 }
-var FormField = forwardRef(({ className, ...props }, ref) => {
-  return /* @__PURE__ */ jsx("div", { ref, className: cn("grid gap-2", className), ...props });
-});
+var FormField = forwardRef(
+  ({ className, label, helperText, errorMessage, required, htmlFor, children, ...props }, ref) => {
+    return /* @__PURE__ */ jsxs("div", { ref, className: cn("grid gap-2", className), ...props, children: [
+      label ? /* @__PURE__ */ jsxs("label", { htmlFor, className: "text-sm font-semibold leading-none text-foreground", children: [
+        label,
+        required ? /* @__PURE__ */ jsx("span", { className: "ml-1 text-destructive", children: "*" }) : null
+      ] }) : null,
+      children,
+      errorMessage ? /* @__PURE__ */ jsx("p", { className: "text-sm text-destructive", children: errorMessage }) : helperText ? /* @__PURE__ */ jsx("p", { className: "text-sm text-muted-foreground", children: helperText }) : null
+    ] });
+  }
+);
 FormField.displayName = "FormField";
 var FormItem = forwardRef(({ className, ...props }, ref) => {
   return /* @__PURE__ */ jsx("div", { ref, className: cn("flex flex-col space-y-2", className), ...props });
@@ -2009,6 +2107,13 @@ var SearchableSelect = forwardRef(
         return candidate.toLowerCase().includes(normalized);
       });
     }, [options, searchTerm]);
+    const normalizeValue = useCallback(
+      (raw) => {
+        const match = options.find((option) => String(option.value) === raw);
+        return match ? match.value : raw;
+      },
+      [options]
+    );
     const handleOpenChange = useCallback(
       (next) => {
         setIsOpen(next);
@@ -2052,7 +2157,7 @@ var SearchableSelect = forwardRef(
           {
             value: value !== void 0 ? String(value) : void 0,
             defaultValue: defaultValue !== void 0 ? String(defaultValue) : void 0,
-            onValueChange: (next) => onChange?.(next),
+            onValueChange: (next) => onChange?.(normalizeValue(next)),
             disabled: disabled || loading,
             onOpenChange: handleOpenChange,
             ...props,
@@ -6513,4 +6618,381 @@ function PageTitle2({
   );
 }
 
-export { Alert, ArgonSidebar, AsyncCombobox, Badge, Breadcrumb, Button, Card, CardAction, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, Combobox, DataTable, FormField as Field, Form, FormControl, FormDescription, FormField, FormItem, FormLabel, FormMessage, Input, LineClampTooltip, Loading, main_fe_exports as MainFe, MultiSelect, NumericInput, OverflowTooltip, PageTitle, Pagination, SearchableSelect, SectionTitle, Select, Sidebar, SidebarItem, Stat, Table, TableBody, TableCell, TableHeader, TableRow, Tabs, Tooltip, TruncatedText, cn, defaultPermissionChecker, filterSidebarItems, hasActiveDescendant };
+// src/ai-manifest.ts
+var uiAiManifest = {
+  packageName: "@lucasvu/scope-ui",
+  styleImport: "@lucasvu/scope-ui/styles.css",
+  rules: [
+    "Import the stylesheet once at the app entry before rendering any component.",
+    "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.",
+    'Always provide a stable rowKey to DataTable and use sortMode="server" when sorting happens on the backend.',
+    "Prefer Card as the outer layout section and keep alerts, stats, and tables inside CardContent when building dashboards or forms.",
+    "Do not import MainFe components unless the target explicitly asks for legacy main-fe styling."
+  ],
+  components: [
+    {
+      name: "Primary action",
+      importName: "Button",
+      purpose: "Render the main clickable action.",
+      useWhen: [
+        "Submitting a form",
+        "Triggering create/save/confirm flows",
+        "Need loading or block width support"
+      ],
+      avoidWhen: [
+        "Pure navigation text links without button semantics"
+      ],
+      props: [
+        { name: "variant", type: "'default' | 'secondary' | 'ghost' | 'outline' | 'destructive' | 'link' | 'confirm' | 'create'", description: "Chooses the visual emphasis." },
+        { name: "size", type: "'sm' | 'md' | 'lg' | 'icon'", description: "Chooses the button size." },
+        { name: "block", type: "boolean", description: "Expands the button to full width." },
+        { name: "loading", type: "boolean", description: "Shows a spinner and disables interaction." }
+      ],
+      example: "<Button variant='create' block>Save changes</Button>",
+      related: ["Alert", "Card"]
+    },
+    {
+      name: "Single-line text input",
+      importName: "Input",
+      purpose: "Capture short text, email, password, number-like strings, or search text.",
+      useWhen: [
+        "A single text value is needed",
+        "You need label/helper/error handling built in",
+        "You need prefix, suffix, or password toggle support"
+      ],
+      props: [
+        { name: "label", type: "ReactNode", description: "Field label rendered above the control." },
+        { name: "helperText", type: "ReactNode", description: "Supplemental guidance shown below." },
+        { name: "errorMessage", type: "ReactNode", description: "Validation message shown below in error state." },
+        { name: "prefix", type: "ReactNode", description: "Visual prefix inside the field." },
+        { name: "suffix", type: "ReactNode", description: "Visual suffix inside the field." }
+      ],
+      example: "<Input label='Email' type='email' placeholder='you@example.com' />",
+      related: ["Textarea", "NumericInput", "Field"]
+    },
+    {
+      name: "Multiline text input",
+      importName: "Textarea",
+      purpose: "Capture longer free-form content.",
+      useWhen: [
+        "The user needs multiple lines of text",
+        "A description, note, or comment field is needed"
+      ],
+      props: [
+        { name: "label", type: "ReactNode", description: "Field label rendered above the textarea." },
+        { name: "rows", type: "number", description: "Controls initial textarea height." },
+        { name: "helperText", type: "ReactNode", description: "Supplemental guidance shown below." },
+        { name: "errorMessage", type: "ReactNode", description: "Validation message shown below in error state." }
+      ],
+      example: "<Textarea label='Description' rows={5} placeholder='Write the details...' />",
+      related: ["Input", "Field"]
+    },
+    {
+      name: "Single select",
+      importName: "Select",
+      purpose: "Pick one value from a small fixed option set.",
+      useWhen: [
+        "Fewer options and no search is required",
+        "A simple dropdown is enough"
+      ],
+      props: [
+        { name: "options", type: "SelectOption[]", required: true, description: "List of selectable options." },
+        { name: "label", type: "ReactNode", description: "Field label rendered above the trigger." },
+        { name: "placeholder", type: "string", description: "Placeholder shown when no value is selected." },
+        { name: "onChange", type: "(value) => void", description: "Returns the original option value type." }
+      ],
+      example: "<Select label='Plan' options={[{ label: 'Starter', value: 'starter' }]} />",
+      related: ["SearchableSelect", "Combobox"]
+    },
+    {
+      name: "Searchable local select",
+      importName: "SearchableSelect",
+      purpose: "Pick one value from a larger in-memory list with search.",
+      useWhen: [
+        "More than a handful of options exist",
+        "Local filtering is enough"
+      ],
+      props: [
+        { name: "options", type: "SearchableSelectOption[]", required: true, description: "List of selectable options." },
+        { name: "searchPlaceholder", type: "string", description: "Placeholder inside the search field." },
+        { name: "onSearch", type: "(query) => void", description: "Receives the local search query." }
+      ],
+      example: "<SearchableSelect label='Country' searchPlaceholder='Search country' options={countries} />",
+      related: ["Select", "Combobox", "AsyncCombobox"]
+    },
+    {
+      name: "Type and pick",
+      importName: "Combobox",
+      purpose: "Let the user type and choose from a filtered list.",
+      useWhen: [
+        "A command-palette-like input is needed",
+        "The typed text should stay visible in the input"
+      ],
+      props: [
+        { name: "options", type: "ComboboxOption[]", required: true, description: "List of options to filter." },
+        { name: "value", type: "string | number", description: "Selected value." },
+        { name: "onChange", type: "(value) => void", description: "Selected value callback." }
+      ],
+      example: "<Combobox label='Assignee' options={users} value={assigneeId} onChange={setAssigneeId} />",
+      related: ["SearchableSelect", "AsyncCombobox"]
+    },
+    {
+      name: "Remote search combobox",
+      importName: "AsyncCombobox",
+      purpose: "Search and pick from server-backed data.",
+      useWhen: [
+        "Options are loaded from an API",
+        "Infinite scroll or async fetching is needed"
+      ],
+      props: [
+        { name: "options", type: "ComboboxOption[]", required: true, description: "Currently loaded options." },
+        { name: "loading", type: "boolean", description: "Shows async loading state." },
+        { name: "onSearch", type: "(query) => void", required: true, description: "Triggers remote search." },
+        { name: "onLoadMore", type: "() => void", description: "Loads more options when scrolling near the end." }
+      ],
+      example: "<AsyncCombobox label='User' options={options} loading={loading} onSearch={searchUsers} />",
+      related: ["Combobox", "SearchableSelect"]
+    },
+    {
+      name: "Multiple selection",
+      importName: "MultiSelect",
+      purpose: "Choose many values from a searchable list.",
+      useWhen: [
+        "The user can pick multiple tags, users, or filters"
+      ],
+      props: [
+        { name: "options", type: "MultiSelectOption[]", required: true, description: "List of selectable options." },
+        { name: "value", type: "Array<string | number>", description: "Selected values." },
+        { name: "onChange", type: "(values) => void", description: "Selected values callback." }
+      ],
+      example: "<MultiSelect label='Tags' options={tagOptions} value={tags} onChange={setTags} />",
+      related: ["Select", "SearchableSelect"]
+    },
+    {
+      name: "Structured field wrapper",
+      importName: "Field",
+      purpose: "Add a shared label/helper/error wrapper around custom content.",
+      useWhen: [
+        "Wrapping a custom control that does not expose label props",
+        "Grouping multiple controls under one heading"
+      ],
+      avoidWhen: [
+        "A built-in form control already renders its own label and helper text"
+      ],
+      props: [
+        { name: "label", type: "ReactNode", description: "Field label rendered above children." },
+        { name: "helperText", type: "ReactNode", description: "Helper text below children." },
+        { name: "errorMessage", type: "ReactNode", description: "Error text below children." },
+        { name: "htmlFor", type: "string", description: "Associates the label with the wrapped control id." }
+      ],
+      example: "<Field label='Schedule' htmlFor='range'><DateRangePicker id='range' /></Field>",
+      related: ["Input", "Textarea", "Select"]
+    },
+    {
+      name: "Data table",
+      importName: "DataTable",
+      purpose: "Render sortable tabular data with optional selection, actions, loading, and pagination.",
+      useWhen: [
+        "Displaying records in rows and columns",
+        "Sort, pagination, selection, or row actions are required"
+      ],
+      props: [
+        { name: "columns", type: "DataTableColumn<T>[]", required: true, description: "Column definitions." },
+        { name: "data", type: "T[]", required: true, description: "Rows to render." },
+        { name: "rowKey", type: "keyof T | ((record: T) => string | number)", required: true, description: "Stable key for each row." },
+        { name: "pagination", type: "DataTablePagination", description: "Enables pagination controls." },
+        { name: "sortMode", type: "'client' | 'server'", description: "Choose client or backend sorting." }
+      ],
+      example: "<DataTable rowKey='id' columns={columns} data={rows} pagination={pagination} />",
+      related: ["Card", "Pagination", "Loading"]
+    },
+    {
+      name: "Status message",
+      importName: "Alert",
+      purpose: "Communicate neutral, success, warning, or danger states.",
+      useWhen: [
+        "You need a visible status or validation banner"
+      ],
+      props: [
+        { name: "tone", type: "'neutral' | 'info' | 'success' | 'warning' | 'danger'", description: "Semantic tone mapping." },
+        { name: "title", type: "ReactNode", description: "Alert headline." },
+        { name: "description", type: "ReactNode", description: "Supporting message." }
+      ],
+      example: "<Alert tone='warning' title='Missing information' description='Please fill all required fields.' />",
+      related: ["Loading", "Card"]
+    },
+    {
+      name: "Layout section",
+      importName: "Card",
+      purpose: "Wrap a coherent chunk of UI in a bordered surface.",
+      useWhen: [
+        "Building forms, dashboards, settings sections, or summary panels"
+      ],
+      props: [
+        { name: "className", type: "string", description: "Adds layout-specific spacing or width." }
+      ],
+      example: "<Card><CardHeader><CardTitle>Account</CardTitle></CardHeader><CardContent>...</CardContent></Card>",
+      related: ["CardHeader", "CardTitle", "CardContent", "CardFooter"]
+    }
+  ]
+};
+
+// src/theme-contract.ts
+var uiThemeContract = {
+  packageName: "@lucasvu/scope-ui",
+  importOrder: [
+    "import '@lucasvu/scope-ui/styles.css'",
+    "import './styles/ui-theme.css'"
+  ],
+  selectors: {
+    light: [":root", "[data-ui-theme='light']"],
+    dark: [".dark", "[data-ui-theme='dark']"]
+  },
+  overrideFile: "src/styles/ui-theme.css",
+  rules: [
+    "Import the package stylesheet before your project theme override stylesheet.",
+    "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.",
+    "For AI-generated screens, choose one theme source of truth and keep component code token-driven."
+  ],
+  tokens: [
+    {
+      name: "--tw-background",
+      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"]
+    },
+    {
+      name: "--tw-foreground",
+      description: "Primary text color in HSL triplet format.",
+      defaultLight: "222.2 47.4% 11.2%",
+      defaultDark: "210 40% 98%",
+      usedBy: ["Button", "Input", "Card", "Typography"]
+    },
+    {
+      name: "--tw-primary",
+      description: "Primary brand color in HSL triplet format.",
+      defaultLight: "221.2 83.2% 53.3%",
+      defaultDark: "217.2 91.2% 59.8%",
+      usedBy: ["Button", "focus rings", "brand emphasis"]
+    },
+    {
+      name: "--tw-accent",
+      description: "Accent color in HSL triplet format.",
+      defaultLight: "199 89% 48%",
+      defaultDark: "199 89% 48%",
+      usedBy: ["Tabs", "checkbox accent", "highlight states"]
+    },
+    {
+      name: "--tw-success",
+      description: "Success state color in HSL triplet format.",
+      defaultLight: "142.1 76.2% 36.3%",
+      defaultDark: "142.1 70.6% 45.3%",
+      usedBy: ["Alert", "confirm buttons", "status text"]
+    },
+    {
+      name: "--tw-destructive",
+      description: "Danger state color in HSL triplet format.",
+      defaultLight: "0 84.2% 60.2%",
+      defaultDark: "0 62.8% 30.6%",
+      usedBy: ["Alert", "destructive buttons", "error states"]
+    },
+    {
+      name: "--tw-border",
+      description: "Border color in HSL triplet format.",
+      defaultLight: "214.3 31.8% 91.4%",
+      defaultDark: "217.2 32.6% 17.5%",
+      usedBy: ["Input", "Select", "Card", "DataTable"]
+    },
+    {
+      name: "--surface",
+      description: "Default surface background as a CSS color.",
+      defaultLight: "rgba(255, 255, 255, 0.92)",
+      defaultDark: "rgba(15, 23, 42, 0.78)",
+      usedBy: ["Tabs", "Pagination", "glass surfaces"]
+    },
+    {
+      name: "--surface-strong",
+      description: "Stronger elevated surface as a CSS color.",
+      defaultLight: "rgba(241, 245, 249, 0.96)",
+      defaultDark: "rgba(30, 41, 59, 0.92)",
+      usedBy: ["Pagination hover", "raised surfaces"]
+    },
+    {
+      name: "--grey",
+      description: "Neutral table/header background as a CSS color.",
+      defaultLight: "rgba(248, 250, 252, 0.96)",
+      defaultDark: "rgba(30, 41, 59, 0.88)",
+      usedBy: ["DataTable header"]
+    },
+    {
+      name: "--grey-strong",
+      description: "Hover background for neutral rows as a CSS color.",
+      defaultLight: "rgba(241, 245, 249, 0.98)",
+      defaultDark: "rgba(51, 65, 85, 0.92)",
+      usedBy: ["DataTable row hover"]
+    },
+    {
+      name: "--text",
+      description: "Generic text color alias as a CSS color.",
+      defaultLight: "hsl(var(--tw-foreground))",
+      defaultDark: "hsl(var(--tw-foreground))",
+      usedBy: ["Pagination", "legacy utility surfaces"]
+    },
+    {
+      name: "--muted",
+      description: "Generic muted text color alias as a CSS color.",
+      defaultLight: "hsl(var(--tw-muted-foreground))",
+      defaultDark: "hsl(var(--tw-muted-foreground))",
+      usedBy: ["Pagination", "DataTable sort icon", "helper text"]
+    },
+    {
+      name: "--accent",
+      description: "Generic accent color alias as a CSS color.",
+      defaultLight: "hsl(var(--tw-accent))",
+      defaultDark: "hsl(var(--tw-accent))",
+      usedBy: ["DataTable checkbox accent", "focus accents"]
+    },
+    {
+      name: "--primary-grad-from",
+      description: "Gradient start color in HSL triplet format.",
+      defaultLight: "199 89% 48%",
+      defaultDark: "198.6 88.7% 48.4%",
+      usedBy: ["Button variant create"]
+    },
+    {
+      name: "--primary-grad-to",
+      description: "Gradient end color in HSL triplet format.",
+      defaultLight: "221.2 83.2% 53.3%",
+      defaultDark: "221.2 83.2% 53.3%",
+      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);
+}`
+};
+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.",
+  "Read uiAiManifest to choose the correct component by intent before coding.",
+  "Read uiThemeContract before changing colors, shadows, or theme behavior.",
+  "Prefer root exports and avoid MainFe unless the task explicitly targets a legacy screen."
+];
+
+export { Alert, ArgonSidebar, AsyncCombobox, Badge, Breadcrumb, Button, Card, CardAction, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, Combobox, FormControl as Control, DataTable, FormDescription as Description, FormField as Field, Form, FormControl, FormDescription, FormField, FormItem, FormLabel, FormMessage, Input, FormItem as Item, FormLabel as Label, LineClampTooltip, Loading, main_fe_exports as MainFe, FormMessage as Message, MultiSelect, NumericInput, OverflowTooltip, PageTitle, Pagination, SearchableSelect, SectionTitle, Select, Sidebar, SidebarItem, Stat, Table, TableBody, TableCell, TableHeader, TableRow, Tabs, Textarea, Tooltip, TruncatedText, cn, defaultPermissionChecker, filterSidebarItems, hasActiveDescendant, uiAiManifest, uiProjectAiRules, uiThemeContract };