tera-system-ui 0.1.64 → 0.1.66

package/dist/llms/alert.md

@@ -0,0 +1,29 @@
+# Alert
+
+Contextual alert banner for status messages.
+
+## Import
+
+  import { Alert } from 'tera-system-ui';
+
+## Alert
+
+### Props
+
+  Name                      Type                                    Required
+  ──────────────────────────────────────────────────────────────────────────
+  variant                   AlertVariant                            optional  
+  title                     string                                  optional  
+  description               string | Snippet                        optional  
+  closable                  boolean                                 optional  
+  icon                      boolean                                 optional  
+  children                  Snippet                                 optional  
+  class                     string                                  optional  
+
+### Usage
+
+  <script>
+    import { Alert } from 'tera-system-ui';
+  </script>
+
+  <Alert>Content</Alert>

package/dist/llms/avatar.md

@@ -0,0 +1,34 @@
+# Avatar
+
+User avatar with image, initials fallback, and size variants.
+
+## Import
+
+  import { Avatar } from 'tera-system-ui';
+  import { Avatar } from 'tera-system-ui/avatar';  // subpath
+
+## Avatar
+
+### Props
+
+  Name                      Type                                    Required
+  ──────────────────────────────────────────────────────────────────────────
+  size                      sm | md | lg | xl                       optional  (default: md)
+  border                    boolean                                 optional  
+  children                  Snippet                                 optional  
+  class                     string                                  optional  
+  alt                       string                                  optional  
+  src                       string                                  optional  
+  ref                       HTMLDivElement                          optional  (bindable)
+  userUid                   string                                  optional  
+  apiUrl                    string                                  optional  
+
+### Usage
+
+  <script>
+    import { Avatar } from 'tera-system-ui';
+  </script>
+
+  <Avatar>Content</Avatar>
+  <Avatar size="sm">Content</Avatar>
+  <Avatar border>Content</Avatar>

package/dist/llms/badge.md

@@ -0,0 +1,31 @@
+# Badge
+
+Compact label for counts, status, or categories.
+
+## Import
+
+  import { Badge } from 'tera-system-ui';
+
+## Badge
+
+### Props
+
+  Name                      Type                                    Required
+  ──────────────────────────────────────────────────────────────────────────
+  variant                   default | primary | success | error...  optional  (default: default)
+  size                      sm | md                                 optional  (default: md)
+  children                  Snippet                                 optional  
+  class                     string                                  optional  
+  dot                       boolean                                 optional  
+  closable                  boolean                                 optional  
+  onclose                   () => void                              optional  
+
+### Usage
+
+  <script>
+    import { Badge } from 'tera-system-ui';
+  </script>
+
+  <Badge>Content</Badge>
+  <Badge variant="primary">Content</Badge>
+  <Badge size="sm">Content</Badge>

package/dist/llms/brand-logo.md

@@ -0,0 +1,30 @@
+# BrandLogo
+
+Brand logo component for consistent identity display.
+
+## Import
+
+  import { BrandLogo } from 'tera-system-ui';
+  import { BrandLogo } from 'tera-system-ui/brand-logo';  // subpath
+
+## BrandLogo
+
+### Props
+
+  Name                      Type                                    Required
+  ──────────────────────────────────────────────────────────────────────────
+  theme                     light | dark | auto                     optional  (default: auto)
+  shape                     square                                  optional  
+  children                  Snippet                                 optional  
+  class                     string                                  optional  
+  ref                       HTMLDivElement                          optional  (bindable)
+
+### Usage
+
+  <script>
+    import { BrandLogo } from 'tera-system-ui';
+  </script>
+
+  <BrandLogo>Content</BrandLogo>
+  <BrandLogo theme="light">Content</BrandLogo>
+  <BrandLogo shape="square">Content</BrandLogo>

package/dist/llms/button.md

@@ -0,0 +1,37 @@
+# Button
+
+Interactive button with variants, sizes, loading state, danger mode, and wave animation.
+
+## Import
+
+  import { Button } from 'tera-system-ui';
+  import { Button } from 'tera-system-ui/button';  // subpath
+
+## Button
+
+### Props
+
+  Name                      Type                                    Required
+  ──────────────────────────────────────────────────────────────────────────
+  variant                   primary | default | dashed | text |...  optional  (default: default)
+  size                      xs | sm | md | lg                       optional  (default: md)
+  shape                     default | circle | round                optional  (default: default)
+  disabled                  boolean                                 optional  
+  loading                   boolean                                 optional  
+  icon                      boolean                                 optional  
+  danger                    boolean                                 optional  
+  block                     boolean                                 optional  
+  children                  Snippet                                 optional  
+  class                     string                                  optional  
+  ref                       HTMLButtonElement                       optional  (bindable)
+
+### Usage
+
+  <script>
+    import { Button } from 'tera-system-ui';
+  </script>
+
+  <Button>Content</Button>
+  <Button variant="primary">Content</Button>
+  <Button size="xs">Content</Button>
+  <Button shape="circle">Content</Button>

package/dist/llms/card.md

@@ -0,0 +1,32 @@
+# Card
+
+Content container with elevation, border, and padding variants.
+
+## Import
+
+  import { Card } from 'tera-system-ui';
+
+## Card
+
+### Props
+
+  Name                      Type                                    Required
+  ──────────────────────────────────────────────────────────────────────────
+  variant                   default | elevated | bordered | ghost   optional  (default: default)
+  padding                   none | sm | md | lg                     optional  (default: md)
+  clickable                 boolean                                 optional  
+  loading                   boolean                                 optional  
+  children                  Snippet                                 optional  
+  class                     string                                  optional  
+  ref                       HTMLDivElement                          optional  (bindable)
+
+### Usage
+
+  <script>
+    import { Card } from 'tera-system-ui';
+  </script>
+
+  <Card>Content</Card>
+  <Card variant="elevated">Content</Card>
+  <Card padding="none">Content</Card>
+  <Card clickable>Content</Card>

package/dist/llms/checkbox.md

@@ -0,0 +1,35 @@
+# Checkbox
+
+Checkbox input with label and indeterminate support.
+
+Built on BitsUI Checkbox primitive.
+
+## Import
+
+  import { Checkbox } from 'tera-system-ui';
+  import { Checkbox } from 'tera-system-ui/checkbox';  // subpath
+
+## Checkbox
+
+### Props
+
+  Name                      Type                                    Required
+  ──────────────────────────────────────────────────────────────────────────
+  class                     string                                  optional  Additional CSS classes for the root element.
+  checked                   boolean                                 optional  Whether the checkbox is checked. Bindable.
+  indeterminate             boolean                                 optional  Whether the checkbox shows an indeterminate (−) state. Bindable.
+  disabled                  boolean                                 optional  Prevents user interaction and dims the control.
+  required                  boolean                                 optional  Whether the checkbox must be checked before form submission.
+  name                      string                                  optional  Name attribute used when submitting within a form.
+  value                     string                                  optional  Value sent with the form when checked.
+  onCheckedChange           (checked: boolean) => void              optional  Called when the checked state changes.
+  children                  Snippet                                 optional  Additional content rendered next to the checkbox indicator.
+  ref                       HTMLButtonElement                       optional  Bindable reference to the root button element.
+
+### Usage
+
+  <script>
+    import { Checkbox } from 'tera-system-ui';
+  </script>
+
+  <Checkbox>Content</Checkbox>

package/dist/llms/colors.md

@@ -0,0 +1,161 @@
+# Color & Token System
+
+Reference for the tera-system-ui design token system.
+Always use semantic tokens in components — never primitive shades.
+
+---
+
+## Naming Convention
+
+  {role}-{modifier}
+
+  Influenced by: Ant Design 5 (state modifiers), GitHub Primer (subtle/muted prominence
+  scale), shadcn/ui (CSS-variable-as-utility, "default" for resting state).
+
+  Prominence scale (lightest → darkest):
+    subtle  →  muted  →  default  →  hover  →  active
+
+  * = auto dark-mode: defined in both :root and :root.dark — no dark: prefix needed
+
+---
+
+## Semantic Tokens — Surfaces
+
+  Tailwind utility      CSS variable               Primitive     Role
+  ─────────────────────────────────────────────────────────────────────────
+  bg-surface            --color-surface            #FFFFFF   Page / app background
+  bg-surface-raised     --color-surface-raised     #FCFCFC   Cards, panels
+  bg-surface-sunken     --color-surface-sunken     #F5F5F5   Inputs (filled), disabled areas
+  bg-surface-hover      --color-surface-hover      #F0F0F0   Hover / pressed neutral bg
+  bg-surface-control    --color-surface-control    #FFFFFF   Interactive controls (button, input outlined, checkbox, select, slider)
+                                                             Light: same as page (white). Dark: elevated gray — sits above both page and dialogs.
+                                                             Use this instead of bg-surface for any interactive control background.
+
+## Semantic Tokens — Borders
+
+  Tailwind utility      CSS variable               Primitive     Role
+  ─────────────────────────────────────────────────────────────────────────
+  border-border-default --color-border-default     #D9D9D9   Default border
+  border-border-strong  --color-border-strong      #BFBFBF   Focus ring, separator
+
+## Semantic Tokens — Text
+
+  Tailwind utility      CSS variable               Primitive     Role
+  ─────────────────────────────────────────────────────────────────────────
+  text-text-primary     --color-text-primary       #000000   Body text, headings
+  text-text-secondary   --color-text-secondary     #595959   Supporting / label text
+  text-text-tertiary    --color-text-tertiary      #8C8C8C   Placeholders, hints
+  text-text-disabled    --color-text-disabled      #BFBFBF   Disabled labels
+
+## Semantic Tokens — Interactive (primary action)
+
+  hover DARKENS for text/border elements (goes 500 → 600 → 700)
+
+  Tailwind utility           CSS variable                Primitive    Role
+  ──────────────────────────────────────────────────────────────────────────────
+  text-interactive           --color-interactive         primary-500  Base link/CTA
+  text-interactive-hover     --color-interactive-hover   primary-600  Hover: darker
+  text-interactive-active    --color-interactive-active  primary-700  Pressed: darkest
+  bg-interactive-subtle      --color-interactive-subtle  primary-50   Ghost bg, tint
+  border-interactive-border  --color-interactive-border  primary-200  Subtle border on tinted bg
+  text-interactive-text      --color-interactive-text    primary-700  Text on tinted bg
+
+  Note: for the primary filled button bg, use bg-primary-600 directly.
+  It reads from --color-primary-600 and responds to theme changes.
+
+  text-interactive-on        --color-interactive-on      #ffffff      Text / icon ON a filled interactive bg
+  bg-overlay                 --color-overlay             black/0.25   Modal / drawer backdrop scrim (dark mode: black/0.5)
+
+## Semantic Tokens — Status (error / warning / success / information)
+
+  hover LIGHTENS (400 < 500) — softens the state on approach.
+  Tokens marked * adapt automatically in dark mode.
+
+  Pattern (same for all four statuses):
+
+  Tailwind utility         Role
+  ────────────────────────────────────────────────────────
+  bg-{status}-subtle    *  Very light tint background
+  bg-{status}-muted     *  Medium tint / pressed bg
+  border-{status}-border*  Subtle border stroke
+  border-{status}-hover    Lighter hover (approach)
+  bg-{status}-default      Main status color (bg)
+  text-{status}-default    Main status color (text)
+  border-{status}-default  Main status color (border)
+  bg-{status}-active       Pressed / active (stronger)
+  text-{status}-text    *  Readable text on light bg
+
+  Example — Error:
+    bg-error-subtle      alert / tag tint bg (dark: error-900)
+    text-error-text      label text on tinted bg (dark: error-400)
+    border-error-default input border in error state
+    border-error-hover   input border hover in error state
+    bg-error-default     filled destructive button bg
+    bg-error-hover       filled destructive hover bg
+    bg-error-active      filled destructive pressed bg
+
+---
+
+## Primitive Color Palettes
+
+  Use semantic tokens above. Reference these only when no semantic equivalent exists.
+
+  ### Neutral scale (inverts in dark mode)
+
+  neutral-token-1  = #FFFFFF  (white — page background)
+  neutral-token-2  = #FCFCFC
+  neutral-token-3  = #F5F5F5  (input / disabled bg)
+  neutral-token-4  = #F0F0F0  (hover state bg)
+  neutral-token-5  = #D9D9D9  (default border)
+  neutral-token-6  = #BFBFBF  (focus border / disabled text)
+  neutral-token-7  = #8C8C8C  (placeholder / hint)
+  neutral-token-8  = #595959  (secondary text)
+  neutral-token-13 = #000000  (primary text)
+
+  ### Primary (brand blue — changes per theme)
+
+  primary-50 … primary-900  (light → dark blue)
+  Base theme: primary-500 = #3B82F6, primary-600 = #2563EB, primary-700 = #1D4ED8
+
+  ### Status palettes (50 → 900)
+
+  error-*         Red — destructive actions, validation failures
+  warning-*       Orange — caution, soft warnings
+  success-*       Green — confirmation, completion
+  information-*   Sky blue — informational, neutral status
+  secondary-*     Pink/rose — secondary accent
+
+---
+
+## Per-Theme Accent Colors
+
+  Each theme may override `--color-secondary-*` to express a unique accent personality.
+  Components using `bg-secondary-*` / `text-secondary-*` utilities pick this up automatically.
+
+  Theme      Secondary color    Purpose
+  ──────────────────────────────────────────────────────
+  Base       Pink / rose-500    Default secondary
+  AI         Cyan-500           Pairs with violet primary; authentic AI aesthetic
+  Marketing  Rose-500           Editorial pop; distinct from brand blue
+  Professional (inherited)      Default pink
+
+  Use `text-secondary-500`, `bg-secondary-50`, `border-secondary-200` etc. as you would
+  any other semantic scale — the theme's accent automatically flows through.
+
+## Dark Mode
+
+  All neutral surface, text, and border tokens auto-invert in :root.dark.
+  Status subtle/muted/border/text tokens also adapt automatically.
+  Components using only semantic tokens require zero dark: prefix classes.
+
+  AI and Marketing dark modes use hue-tinted elevation steps and colored shadows
+  (violet for AI, navy-blue for Marketing) to create an atmospheric feel.
+  The base dark mode uses near-black (#090909) instead of pure black for less harshness.
+
+## Tailwind Utility Pattern
+
+  bg-surface            → background-color: var(--color-surface)
+  text-text-primary     → color: var(--color-text-primary)
+  border-border-default → border-color: var(--color-border-default)
+  bg-error-subtle       → background-color: var(--color-error-subtle)
+  text-error-text       → color: var(--color-error-text)

package/dist/llms/combobox.md

@@ -0,0 +1,40 @@
+# Combobox
+
+Searchable combo-box with autocomplete.
+
+Built on BitsUI Combobox primitive with client-side filtering.
+
+## Import
+
+  import { Combobox } from 'tera-system-ui';
+  import { Combobox } from 'tera-system-ui/combobox';  // subpath
+
+## Combobox
+
+### Props
+
+  Name                      Type                                    Required
+  ──────────────────────────────────────────────────────────────────────────
+  type                      'single' | 'multiple'                   required  Whether one or many items can be selected at once.
+  items                     ComboboxItem[]                          required  List of selectable options.
+  value                     string | string[]                       optional  Currently selected value(s). Bindable.
+  placeholder               string                                  optional  Placeholder shown in the search input when nothing is selected.
+  disabled                  boolean                                 optional  Prevents all interaction.
+  loop                      boolean                                 optional  Whether keyboard navigation wraps at the list boundaries.
+  allowDeselect             boolean                                 optional  Allow deselecting the current value by clicking it again (single mode only).
+  onchange                  (value: string | string[]) => void      optional  Called when the selection changes.
+  class                     string                                  optional  Additional CSS classes for the root container.
+  ref                       HTMLElement                             optional  Bindable reference to the trigger element.
+  name                      string                                  optional  Name for the hidden form input, enabling native form submission.
+  required                  boolean                                 optional  Marks the field as required for form validation.
+  scrollAlignment           'nearest' | 'center'                    optional  Scroll alignment for the highlighted item.
+  freeInput                 boolean                                 optional  When true (single mode only), whatever the user types becomes the combobox value directly — like a text input with suggestions. Selecting an item from the list still sets its item.value as normal.
+
+### Usage
+
+  <script>
+    import { Combobox } from 'tera-system-ui';
+  </script>
+
+  <Combobox />
+  <Combobox onchange={(v) => console.log(v)} />

package/dist/llms/command.md

@@ -0,0 +1,7 @@
+# command
+
+Command palette. Parts: Command, CommandInput, CommandList, CommandItem, CommandGroup, CommandEmpty, CommandSeparator, CommandShortcut.
+
+## Import
+
+  import {  } from 'tera-system-ui';

package/dist/llms/date-range-picker.md

@@ -0,0 +1,36 @@
+# DateRangePicker
+
+Date range picker with quick-select presets, optional time support, and popover/drawer UI.
+
+Built on BitsUI RangeCalendar and Popover primitives.
+
+## Import
+
+  import { DateRangePicker } from 'tera-system-ui';
+
+## DateRangePicker
+
+### Props
+
+  Name                      Type                                    Required
+  ──────────────────────────────────────────────────────────────────────────
+  dateRange                 Date[]                                  optional  The currently selected date range as a two-element array [start, end]. Bindable.
+  onchange                  (date: Date[]) => void                  optional  Called when the user applies a new date range.
+  enableTime                boolean                                 optional  When true, shows hour and minute pickers alongside the calendar.
+  placeholder               string                                  optional  Placeholder text shown in the trigger when no range is selected.
+  disabled                  boolean                                 optional  Prevents all interaction.
+  class                     string                                  optional  Additional CSS classes for the trigger button.
+  minValue                  CalendarDate                            optional  Earliest selectable date. Use `import { CalendarDate } from '@internationalized/date'` to construct values.
+  maxValue                  CalendarDate                            optional  Latest selectable date. Use `import { CalendarDate } from '@internationalized/date'` to construct values.
+  isDateDisabled            (date: CalendarDate) => boolean         optional  Returns true for dates that should be shown as disabled and unselectable.
+  numberOfMonths            1 | 2                                   optional  Number of calendar months shown side-by-side (desktop only). Defaults to 2.
+  weekStartsOn              0 | 1 | 2 | 3 | 4 | 5 | 6               optional  Day of the week the calendar grid starts on. 0 = Sunday, 1 = Monday, … 6 = Saturday.
+
+### Usage
+
+  <script>
+    import { DateRangePicker } from 'tera-system-ui';
+  </script>
+
+  <DateRangePicker />
+  <DateRangePicker onchange={(v) => console.log(v)} />

package/dist/llms/dialog.md

@@ -0,0 +1,45 @@
+# Dialog
+
+Modal dialog with header/footer snippet slots, size variants, and focus management.
+
+Built on BitsUI Dialog primitive.
+
+## Import
+
+  import { Dialog } from 'tera-system-ui';
+  import { Dialog } from 'tera-system-ui/dialog';  // subpath
+
+## Dialog
+
+### Props
+
+  Name                      Type                                    Required
+  ──────────────────────────────────────────────────────────────────────────
+  children                  Snippet                                 optional  
+  header                    Snippet                                 optional  Snippet rendered in the dialog header area.
+  footer                    Snippet                                 optional  Snippet rendered in the dialog footer area.
+  open                      boolean                                 optional  Whether the dialog is open. Bindable.
+  class                     string                                  optional  Additional CSS classes for the dialog content panel.
+  size                      'xs' | 'sm' | 'md' | 'lg' | 'full' ...  optional  Controls the maximum width of the dialog panel.
+  position                  'top' | 'center'                        optional  Vertical alignment of the dialog on screen.
+  padding                   'none'                                  optional  Set to 'none' to remove internal padding.
+  closeOnClickOutside       boolean                                 optional  Whether clicking the backdrop closes the dialog.
+  closeButton               boolean                                 optional  Whether to render a close (×) button in the header.
+  staticRender              boolean                                 optional  When true the dialog DOM is kept alive after close — children preserve internal state between open/close cycles.
+  preventScroll             boolean                                 optional  Prevent the page from scrolling while the dialog is open.
+  onOpenChangeComplete      (open: boolean) => void                 optional  Called after the open or close animation has fully completed. Note: This callback only fires when the internal component mutates the open state, not when the state is changed by outside)
+  triggerRef                HTMLElement                             optional  Element to return focus to when the dialog closes.
+  focusTriggerAfterClose    boolean                                 optional  Focus triggerRef after close (default true when triggerRef is provided).
+  containerClass            string                                  optional  Additional classes applied to the outer container div.
+  headerClass               string                                  optional  Additional classes applied to the header region.
+  bodyClass                 string                                  optional  Additional classes applied to the body/content region.
+  footerClass               string                                  optional  Additional classes applied to the footer region.
+  ref                       HTMLElement                             optional  Bindable reference to the dialog content element.
+
+### Usage
+
+  <script>
+    import { Dialog } from 'tera-system-ui';
+  </script>
+
+  <Dialog>Content</Dialog>

package/dist/llms/drawer.md

@@ -0,0 +1,30 @@
+# Drawer
+
+Side drawer that slides in from the screen edge.
+
+## Import
+
+  import { Drawer } from 'tera-system-ui';
+
+## Drawer
+
+### Props
+
+  Name                      Type                                    Required
+  ──────────────────────────────────────────────────────────────────────────
+  open                      boolean                                 optional  
+  side                      DrawerSide                              optional  
+  size                      DrawerSize                              optional  
+  closeOnClickOutside       boolean                                 optional  
+  header                    Snippet                                 optional  
+  footer                    Snippet                                 optional  
+  children                  Snippet                                 optional  
+  onclose                   () => void                              optional  
+
+### Usage
+
+  <script>
+    import { Drawer } from 'tera-system-ui';
+  </script>
+
+  <Drawer>Content</Drawer>