@urbicon-ui/design-content 6.1.8

package/content/blocks/components/calendar/llm.txt

@@ -0,0 +1,105 @@
+
+---
+
+## Calendar
+Flexible calendar component with month, year, week, and day views.
+Renders timed appointments, multi-day spans and recurrence on a time grid, with
+event display, date selection and configurable layout. For a headless grid that
+buckets your own domain content (meals, shifts, bookings) per day, use `Planner`.
+
+**Import:** `import { Calendar } from '@urbicon-ui/blocks';`
+
+### Examples
+```svelte
+<Calendar
+  events={wasteEvents}
+  categories={wasteCategories}
+  bind:value={selectedDate}
+  showEventList
+  showLegend
+  locale="de-DE"
+/>
+```
+
+```svelte
+<Calendar view="week" bind:value={selectedDate} />
+```
+
+```svelte
+<Calendar selectionMode="range" bind:value={dateRange}>
+  {#snippet children()}
+    <CalendarHeader showViewSwitcher />
+    <CalendarGrid />
+  {/snippet}
+</Calendar>
+```
+
+### Variants
+- variant: bordered, default, ghost (default: default)
+- size: lg, md, sm (default: md)
+
+### Api
+| Prop | Type | Required | Default | Description |
+| --- | --- | :---: | --- | --- |
+| ...CalendarVariants | `VariantProps` | no |  | Styling variants from CalendarVariants |
+| ...HTMLAttributes<HTMLDivElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children') |
+| agendaDays | `number` | no | 30 | Number of days shown in agenda view. |
+| animated | `boolean` | no | true | Enable animated transitions for navigation. |
+| categories | `CalendarEventCategory[]` | no | [] | Event categories for color coding and legend. |
+| children | `Snippet` | no |  | Default children snippet for custom layout composition. |
+| class | `string` | no |  | Extra CSS classes on the root element. |
+| dayCell | `Snippet<[DayCellContext]>` | no |  | Custom snippet for rendering a day cell. |
+| defaultDate | `Date` | no |  | Initial reference day the grid is anchored on, without selecting it. Use this to open a **week** or **day** view on a specific week — `defaultMonth`/ `defaultYear` resolve to the 1st, whose week can fall mostly in the previous month. Ignored when `value` is set (the selection anchors instead); takes priority over `defaultMonth`/`defaultYear`. Read at mount only. |
+| defaultMonth | `number` | no |  | Initial displayed month (0–11). Used only when `value` and `defaultDate` are unset; when `value` is provided, the calendar opens on the value's month. Best for month/year views — for week/day views prefer `defaultDate`. Defaults to current month. |
+| defaultYear | `number` | no |  | Initial displayed year. Used only when `value` is unset; when `value` is provided, the calendar opens on the value's year. Defaults to current year. |
+| disabled | `boolean` | no | false | Disable the entire calendar. |
+| disabledDates | `Date[]` | no |  | Specific dates that are disabled (not selectable). |
+| draggable | `boolean` | no | false | Enable drag & drop to move events between dates. |
+| eventItem | `Snippet<[EventItemContext]>` | no |  | Custom snippet for rendering an event item in the detail list. |
+| eventPopover | `boolean` | no | false | Show a rich popover on hover/focus for days with events (month view). |
+| events | `CalendarEvent[]` | no | [] | Array of events to display on the calendar. |
+| fixedWeeks | `boolean` | no | false | Always show 6 weeks in the grid. |
+| header | `Snippet<[HeaderContext]>` | no |  | Custom snippet for the header area. |
+| isDateDisabled | `(date: Date) => boolean` | no |  | Function to test whether a date is disabled. |
+| locale | `string` | no | 'de-DE' | BCP 47 locale tag for date formatting. |
+| maxDate | `Date` | no |  | Latest selectable/navigable date. |
+| minDate | `Date` | no |  | Earliest selectable/navigable date. |
+| miniCalendarPosition | `'left' | 'right'` | no | 'left' | Position of the mini calendar sidebar. |
+| mint | `MintProp` | no |  | Micro-interaction preset. |
+| onDateClick | `(date: Date) => void` | no |  | Fires when a date cell is clicked (regardless of selection change). |
+| onDateCreate | `(date: Date, view: CalendarViewMode) => void` | no |  | Fires on double-click on a day cell for event creation. The consumer shows their own form. |
+| onDayChange | `(date: Date) => void` | no |  | Fires when the displayed day changes (day view). |
+| onEventClick | `(event: CalendarEvent) => void` | no |  | Fires when an event is clicked. |
+| onEventMove | `(event: CalendarEvent, newStart: Date, newEnd: Date) => void` | no |  | Fires when an event is moved via drag & drop. |
+| onEventResize | `(event: CalendarEvent, newEnd: Date) => void` | no |  | Fires when an event is resized via drag handle. |
+| onMonthChange | `(month: number, year: number) => void` | no |  | Fires when the displayed month/year changes via navigation. |
+| onTimeSlotCreate | `(start: Date, end: Date) => void` | no |  | Fires on click on an empty time slot for event creation. Returns default 1h duration. |
+| onValueChange | `(value: CalendarSelection) => void` | no |  | Fires when the selected date(s) change. |
+| onViewChange | `(view: CalendarViewMode) => void` | no |  | Fires when the view mode changes. |
+| onWeekChange | `(weekStart: Date) => void` | no |  | Fires when the displayed week changes (week view). |
+| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ Calendar: {...} }}>`. Prefer this over `class` overrides when the requested look falls outside the semantic intent palette — presets keep hover/active/dark-mode logic coherent and make the custom look reusable across the project. |
+| resizable | `boolean` | no | false | Enable resize handles on timed events in the time grid. |
+| selectionMode | `'single' | 'range' | 'multiple'` | no | 'single' | SelectionMode property for the Calendar component |
+| showEventList | `boolean` | no |  | Whether to show the detail list when a date is selected. Auto-enabled when events are provided. |
+| showLegend | `boolean` | no |  | Whether to show the built-in legend. Defaults to true when categories are provided. |
+| showMiniCalendar | `boolean` | no | false | Show a mini month calendar sidebar (week/day/agenda views). |
+| showOutsideDays | `boolean` | no | true | Show days from previous/next months to fill the grid. |
+| showTimeGrid | `boolean` | no |  | Show time grid in week/day views. Auto-detected from events with allDay: false. |
+| showViewSwitcher | `boolean` | no | true | Show the view switcher in the header. |
+| showWeekNumbers | `boolean` | no | false | Show ISO week numbers in the left margin. |
+| size | `'sm' | 'md' | 'lg'` | no | 'md' | Size variant that controls dimensions and spacing of the Calendar |
+| slotClasses | `Partial<Record<CalendarSlotName, string>>` | no |  | Per-slot class overrides. |
+| swipeable | `boolean` | no | true | Enable swipe gestures for touch navigation. |
+| timeGridEndHour | `number` | no | 20 | Last visible hour in time grid (exclusive). |
+| timeGridInterval | `30 | 60` | no | 60 | Time slot interval in minutes. |
+| timeGridStartHour | `number` | no | 7 | First visible hour in time grid. |
+| unstyled | `boolean` | no |  | Strip all default tv() classes. |
+| value | `CalendarSelection` | no |  | Currently selected date(s). Supports bind:value. |
+| variant | `'default' | 'bordered' | 'ghost'` | no | 'default' | Visual style variant for the Calendar component |
+| view | `CalendarViewMode` | no | 'month' | Active view mode. Supports bind:view. |
+| views | `CalendarViewMode[]` | no | ['month', 'week', 'day', 'year', 'agenda'] | Which views appear in the view switcher. |
+| weekStartsOn | `0 | 1 | 2 | 3 | 4 | 5 | 6` | no | 1 | First day of the week. 0 = Sunday, 1 = Monday. |
+
+Inherited from:
+- Omit<CalendarVariants, 'dayState' | 'hasEvents'> (omit-pattern)
+- Omit<HTMLAttributes<HTMLDivElement>, 'children'> (omit-pattern)

package/content/blocks/components/chart-frame/llm.txt

@@ -0,0 +1,38 @@
+
+---
+
+## ChartFrame
+Responsive SVG chart shell: measures its width via
+ResizeObserver, applies plot margins, and hands the drawable plot geometry
+to a child snippet. The building block under every cartesian chart in the
+family — use it directly only for fully custom marks.
+
+**Import:** `import { ChartFrame } from '@urbicon-ui/blocks';`
+
+### Examples
+```svelte
+<ChartFrame height={200} ariaLabel="Weekly revenue">
+  {#snippet children({ innerWidth, innerHeight })}
+    <!-- map your data onto innerWidth / innerHeight, then draw SVG marks -->
+    <polyline points={pts} fill="none" class="stroke-primary" stroke-width="2" />
+  {/snippet}
+</ChartFrame>
+```
+
+### Api
+| Prop | Type | Required | Default | Description |
+| --- | --- | :---: | --- | --- |
+| ...HTMLAttributes<HTMLElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children') |
+| ariaLabel | `string` | no |  | Accessible label for the chart image (role="img"). |
+| children | `Snippet<[ChartPlot]>` | no |  | Renders the SVG plot content; receives the  geometry. |
+| class | `string` | no |  | Extra classes merged onto the <figure> wrapper. |
+| fallback | `Snippet` | no |  | Screen-reader fallback (e.g. a data table) rendered visually hidden. |
+| height | `number` | no | 240 | Fixed SVG height in px. |
+| legend | `Snippet` | no |  | Optional legend rendered (as HTML) below the SVG. |
+| margin | `ChartMargin` | no |  | Plot margins; merged over the frame defaults. |
+| slotClasses | `ChartSlotClasses` | no |  | Per-slot class overrides. |
+| unstyled | `boolean` | no |  | Remove all default tv classes. |
+| width | `number` | no |  | Fixed width in px. Omit for responsive width measured from the container (the common case); set it only for SSR-stable, non-responsive output. |
+
+Inherited from:
+- Omit<HTMLAttributes<HTMLElement>, 'children'> (omit-pattern)

package/content/blocks/components/command-palette/llm.txt

@@ -0,0 +1,60 @@
+
+---
+
+## CommandPalette
+Keyboard-driven command palette with search, grouped results,
+and arrow-key navigation. Composes Dialog + search input into a ready-to-use overlay.
+Open via bind:open or the built-in Cmd+K shortcut.
+
+**Import:** `import { CommandPalette } from '@urbicon-ui/blocks';`
+
+### Examples
+```svelte
+<CommandPalette
+  items={commands}
+  bind:open
+  onSelect={(item) => handleCommand(item)}
+  placeholder="Type a command..."
+/>
+```
+
+```svelte
+<CommandPalette
+  items={[
+    { id: 'new', label: 'New File', category: 'File', shortcut: 'Ctrl+N' },
+    { id: 'open', label: 'Open File', category: 'File', shortcut: 'Ctrl+O' },
+    { id: 'theme', label: 'Toggle Theme', category: 'Settings' },
+    { id: 'search', label: 'Search', category: 'Navigation', shortcut: 'Ctrl+F' }
+  ]}
+  bind:open={paletteOpen}
+  onSelect={(item) => runAction(item.id)}
+  size="md"
+  showFooter
+/>
+```
+
+### Variants
+- size: lg, md, sm (default: md)
+
+### Api
+| Prop | Type | Required | Default | Description |
+| --- | --- | :---: | --- | --- |
+| items | `CommandPaletteItem[]` | yes |  | Items to display. Grouped automatically by `category`. |
+| class | `string` | no |  | Additional CSS classes on the root wrapper. |
+| customEmpty | `Snippet<[query: string]>` | no |  | Custom empty-state renderer. Receives the current query string. |
+| customItem | `Snippet<[item: CommandPaletteItem, highlighted: boolean, index: number]>` | no |  | Custom item renderer. Receives the item, whether it is highlighted, and its flat index. |
+| emptyText | `string` | no | 'No results found.' | Message shown when the filter returns no results. |
+| filter | `(item: CommandPaletteItem, query: string) => boolean` | no |  | Custom filter function. Receives each item and the current query. Return `true` to keep the item. When omitted, a case-insensitive label + category substring match is used. |
+| onOpenChange | `(open: boolean) => void` | no |  | Fired when the open state changes (close via Escape, backdrop, or selection). |
+| onSelect | `(item: CommandPaletteItem) => void` | no |  | Fired when an item is selected via click or Enter. |
+| open | `boolean` | no | false | Controls visibility. Supports `bind:open`. |
+| placeholder | `string` | no | 'Search...' | Placeholder text for the search input. |
+| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ CommandPalette: {...} }}>`. Prefer this over `class` overrides when the requested look falls outside the semantic intent palette — presets keep hover/active/dark-mode logic coherent and make the custom look reusable across the project. |
+| shortcut | `string | false` | no | 'mod+k' (Cmd+K / Ctrl+K) | Register a global keyboard shortcut that toggles the palette. Set to `false` to disable. |
+| showFooter | `boolean` | no | true | Show keyboard-shortcut hints in the footer. |
+| size | `CommandPaletteVariants['size']` | no | 'md' | Maximum width of the palette panel. |
+| slotClasses | `Partial<Record<'wrapper' | 'input' | 'inputIcon' | 'clearButton' | 'list' | 'group' | 'groupLabel' | 'item' | 'itemHighlighted' | 'itemDefault' | 'itemDisabled' | 'itemIcon' | 'itemLabel' | 'itemShortcut' | 'empty' | 'footer' | 'kbd', string>>` | no |  | Per-slot class overrides. |
+| unstyled | `boolean` | no | false | Strip all default styles. |
+
+### Slots (slotClasses keys)
+`wrapper`, `input`, `inputIcon`, `clearButton`, `list`, `group`, `groupLabel`, `item`, `itemHighlighted`, `itemDefault`, `itemDisabled`, `itemIcon`, `itemLabel`, `itemShortcut`, `empty`, `footer`, `kbd`

package/content/blocks/components/composition-bar/llm.txt

@@ -0,0 +1,69 @@
+
+---
+
+## CompositionBar
+Stacked bar with legend that breaks an aggregate value down into
+its components. Suited for budget splits, pool composition, resource
+allocation, token vesting — anywhere `pool = a + b + c` should be visible
+at a glance.
+
+Small segments (< 2% of the total width) are kept minimally visible;
+hovering/focusing the bar or the legend highlights the counterpart in
+sync. Tooltip content is fully overridable via the `tooltip` snippet.
+
+**Import:** `import { CompositionBar } from '@urbicon-ui/blocks';`
+
+### Examples
+```svelte
+<CompositionBar
+  items={[
+    { label: 'Gas',         value: 220609, intent: 'primary' },
+    { label: 'Power',       value: 112731, intent: 'secondary' },
+    { label: 'Maintenance', value:  36102, intent: 'success' }
+  ]}
+  formatValue={(v) => formatCurrency(v)}
+  size="lg"
+  legendPlacement="right"
+  showTotal
+/>
+```
+
+### Variants
+- size: lg, md, sm (default: md)
+- legendPlacement: bottom, left, none, right, top (default: bottom)
+- orientation: horizontal, vertical (default: horizontal)
+
+### Api
+| Prop | Type | Required | Default | Description |
+| --- | --- | :---: | --- | --- |
+| items | `CompositionItem[]` | yes |  | Composition shares in the order they should appear in the bar. |
+| ...CompositionBarVariants | `VariantProps` | no |  | Styling variants from CompositionBarVariants |
+| ...HTMLAttributes<HTMLDivElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children') |
+| class | `string` | no |  | Extra classes merged onto the wrapper. |
+| formatPercent | `(percent: number) => string` | no |  | Format function for percentages. Default: 1 fraction digit, formatted with the active locale (e.g. `12.3 %`). |
+| formatValue | `(value: number) => string` | no |  | Format function for values (tooltip, legend, total). |
+| intent | `CompositionBarIntent` | no | 'primary' | Default intent for items without their own `intent`/`color`. |
+| legendItem | `Snippet<[item: CompositionItem, percent: number]>` | no |  | Custom rendering of a legend entry. Receives the item and its percentage. Fully replaces the default rendering (dot + label + value/percent). |
+| minSegmentPercent | `number` | no | 1.5 | Minimum segment width in percent. Values below it are raised to this width so they stay visible in the bar (nothing gets swallowed). Larger segments are shrunk proportionally so the sum still adds up to 100%. |
+| mint | `MintProp` | no | 'none' | Micro-interaction preset. |
+| onItemSelect | `(item: CompositionItem, index: number) => void` | no |  | Selection callback fired when a bar segment or legend entry is clicked. Receives the item and its index. Makes the bar interactive (cursor + click handler). |
+| preset | `string` | no |  | Preset name (registered via `<BlocksProvider presets={{ CompositionBar: {...} }}>`). |
+| showLegend | `boolean` | no | true | ShowLegend property for the CompositionBar component |
+| showPercentages | `boolean` | no | true | Show percentages in legend and tooltip. |
+| showTotal | `boolean` | no | false | Render the total value after the legend. |
+| showValues | `boolean` | no | false | Render the value directly inside the bar segment (in addition to the legend). Narrow segments are skipped automatically to prevent overflow — only segments with sufficient width (≥ 8% or ~40 px) show their value. Useful for print, PDF attachments, or dense dashboards where hover tooltips are not enough. |
+| slotClasses | `Partial<Record<'wrapper' | 'barWrapper' | 'bar' | 'segment' | 'segmentRest' | 'tooltip' | 'tooltipLabel' | 'tooltipDetail' | 'legend' | 'legendItem' | 'legendDot' | 'legendLabel' | 'legendValue' | 'total' | 'totalLabel', string>>` | no |  | Per-slot class overrides. |
+| tooltip | `Snippet<[item: CompositionItem, percent: number]>` | no |  | Custom tooltip content. Replaces the default layout (label, value, percent). |
+| total | `number` | no |  | Optional fixed total value. Default: Σ items.value. If the explicit total exceeds the sum, the remaining area is rendered neutrally ("unaccounted share"). If it is below the sum, segments are scaled to 100% and a console warning is emitted. |
+| totalLabel | `string` | no |  | Label rendered before the total. Defaults to the localized "Total" label from the blocks i18n bundle. |
+| unstyled | `boolean` | no |  | Remove all default classes; only the layout structure remains. |
+| size | `'lg' | 'md' | 'sm'` | no | md | Controls the dimensions, padding, and text size of the CompositionBar. Affects the component's physical footprint. Available options: lg, md, sm. |
+| legendPlacement | `'bottom' | 'left' | 'none' | 'right' | 'top'` | no | bottom | Controls the legendPlacement behavior and appearance of the CompositionBar component. Available options: bottom, left, none, and 2 more. |
+| orientation | `'horizontal' | 'vertical'` | no | horizontal | Controls the orientation behavior and appearance of the CompositionBar component. Available options: horizontal, vertical. |
+
+Inherited from:
+- Omit<CompositionBarVariants, 'isHovered'> (omit-pattern)
+- Omit<HTMLAttributes<HTMLDivElement>, 'children'> (omit-pattern)
+
+### Slots (slotClasses keys)
+`wrapper`, `barWrapper`, `bar`, `segment`, `segmentRest`, `tooltip`, `tooltipLabel`, `tooltipDetail`, `legend`, `legendItem`, `legendDot`, `legendLabel`, `legendValue`, `total`, `totalLabel`

package/content/blocks/components/currency-input/llm.txt

@@ -0,0 +1,65 @@
+
+---
+
+## CurrencyInput
+Locale-aware monetary input that stores values in **minor units**
+(cents for EUR/USD, pennies for GBP, etc.). While focused the user types raw
+digits with a single decimal separator; on blur the value is reformatted with
+the locale's grouping separators. The currency symbol is rendered as a static
+adornment (left or right of the field) and stays visible at all times.
+
+Storing cents as integers avoids floating-point drift when summing, sorting,
+or persisting amounts. Parsing also goes through string splits — never
+`parseFloat * factor` — so values like `1,005` round to the expected
+`100` minor units (instead of `99` due to IEEE-754 drift). Use
+ for currencies with non-2 decimal
+places (JPY = 0, BHD = 3).
+
+**Import:** `import { CurrencyInput } from '@urbicon-ui/blocks';`
+
+### Examples
+```svelte
+<script>
+let priceCents = $state(1234_56); // 1.234,56 €
+</script>
+<CurrencyInput label="Price" bind:value={priceCents} />
+```
+
+```svelte
+<CurrencyInput
+label="Amount"
+bind:value={amountCents}
+locale="en-US"
+currency="USD"
+symbolPosition="prefix"
+/>
+```
+
+```svelte
+<CurrencyInput bind:value={yen} locale="ja-JP" currency="JPY" precision={0} />
+```
+
+### Api
+| Prop | Type | Required | Default | Description |
+| --- | --- | :---: | --- | --- |
+| currency | `string` | no | 'EUR' | ISO-4217 currency code. Determines the symbol when  is `'prefix'` or `'suffix'`. |
+| locale | `string` | no | 'de-DE' | BCP 47 locale used for formatting (`Intl.NumberFormat`). Controls grouping separator (`.` vs `,`) and decimal separator. Pass `'auto'` to defer to the runtime locale (`Intl.NumberFormat().resolvedOptions().locale`) — i.e. the user's browser language. Note that the runtime locale on the server (Node) and in the browser typically differ, so SSR pages using `'auto'` may briefly show a different format on initial render before hydration. `currency` is intentionally **not** auto-detected, since it is orthogonal to locale (a `de-CH` user may still bill in EUR). |
+| name | `string` | no |  | Shared `name` for native form submission. When set, a hidden input is rendered carrying the integer minor-unit value (matching ) — never the locale-formatted display string. The visible Input itself stays unnamed so the formatted text is not submitted alongside.  Empty / `null` values submit as `""` so the field still appears in the FormData payload (consumers can disambiguate "untouched" via server-side schema parsing). |
+| onValueChange | `(cents: number | null) => void` | no |  | Fires whenever the parsed value changes. Receives the new value in minor units (or `null`). |
+| precision | `number` | no | 2 | Number of fractional digits stored in . For most currencies `2`; for JPY use `0`, for BHD/KWD use `3`. |
+| symbolPosition | `CurrencySymbolPosition` | no | 'suffix' | Where the currency symbol is rendered as a static adornment. The symbol is shown in the input's left or right icon slot (always visible, including while focused) — it is never embedded in the editable text. Use `'none'` for headless numeric editing (no symbol shown at all). |
+| value | `number | null` | no | null | Current monetary value in **minor units** (e.g. cents). Use `null` for "no value entered yet"; the input renders empty. |
+
+Inherited from:
+- Omit<
+    InputProps,
+    | 'type'
+    | 'value'
+    | 'onClear'
+    | 'inputmode'
+    | 'oninput'
+    | 'onchange'
+    | 'onblur'
+    | 'onfocus'
+    | 'name'
+  > (omit-pattern)

package/content/blocks/components/date-picker/llm.txt

@@ -0,0 +1,90 @@
+
+---
+
+## DatePicker
+Date input with calendar popup for selecting a single date. Supports min/max constraints, disabled dates, and format customization.
+
+The `value` prop accepts either a `Date` or an ISO timestamp string —
+useful when surrounding state is hydrated from JSON or a SQL driver
+that serialises timestamps as strings. `onValueChange` always reports
+back a `Date` (or `undefined`); use `toDateInputValue` from
+`@urbicon-ui/blocks` to project it back into a string state.
+
+**Import:** `import { DatePicker } from '@urbicon-ui/blocks';`
+
+### Examples
+```svelte
+<DatePicker
+  bind:value={selectedDate}
+  label="Date of birth"
+  placeholder="Select a date"
+  locale="en-US"
+  clearable
+/>
+```
+
+```svelte
+<script>
+import { DatePicker, toDateInputValue } from '@urbicon-ui/blocks';
+let isoDate = $state('2026-04-22T08:00:00Z');
+</script>
+<DatePicker
+value={isoDate}
+onValueChange={(d) => (isoDate = toDateInputValue(d))}
+label="Period start"
+/>
+```
+
+```svelte
+<DatePicker
+  bind:value={deadline}
+  label="Deadline"
+  minDate={new Date()}
+  maxDate={new Date(2026, 11, 31)}
+  isDateDisabled={(d) => d.getDay() === 0 || d.getDay() === 6}
+  required
+  error={deadlineError}
+/>
+```
+
+### Api
+| Prop | Type | Required | Default | Description |
+| --- | --- | :---: | --- | --- |
+| ...HTMLAttributes<HTMLDivElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children') |
+| calendarVariant | `'default' | 'bordered' | 'ghost'` | no | 'default' | Visual style of the calendar popup. |
+| class | `string` | no |  | Additional CSS classes to apply to the DatePicker component |
+| clearable | `boolean` | no | true | Allow clearing the selected date. |
+| closeOnClickOutside | `boolean` | no | true | Whether the popover closes on outside click. |
+| closeOnEscape | `boolean` | no | true | Whether the popover closes on Escape key. |
+| closeOnSelect | `boolean` | no | true | Close popover after selecting a date. |
+| defaultMonth | `MonthIndex` | no |  | Default month shown when the picker opens without a value. `0`–`11`. |
+| defaultYear | `number` | no |  | Default year shown when the picker opens without a value. |
+| disabled | `boolean` | no | false | Disable the entire picker. |
+| disabledDates | `Date[]` | no |  | Specific dates that are disabled. |
+| displayFormat | `DateFormatOptions` | no |  | Intl.DateTimeFormat options for the displayed date. |
+| error | `string` | no |  | Error message shown below the input. |
+| fixedWeeks | `boolean` | no | false | Always show 6 weeks. |
+| helper | `string` | no |  | Helper text shown below the input. |
+| inputVariant | `'outlined' | 'filled' | 'ghost' | 'underline'` | no | 'outlined' | InputVariant property for the DatePicker component |
+| isDateDisabled | `(date: Date) => boolean` | no |  | Predicate that disables specific dates. Errors thrown by the predicate are caught and logged; the date is then treated as allowed so a faulty consumer callback can't take the picker down. |
+| label | `string` | no |  | Label above the input. |
+| locale | `string` | no | 'de-DE' | BCP 47 locale for date formatting and calendar. |
+| maxDate | `Date` | no |  | Latest selectable date. |
+| minDate | `Date` | no |  | Earliest selectable date. |
+| mint | `MintProp` | no |  | Micro-interaction preset. |
+| name | `string` | no |  | Shared `name` for native form submission. When set, a hidden input is rendered carrying the serialized date — matching what the user picked, so the visible input's locale-formatted display string is never submitted instead.  Empty / unset values submit as `""` so the field still appears in the FormData payload. |
+| onClickOutside | `() => void` | no |  | Fires after an outside click closes the popover. Notification only — does NOT govern whether close happens. That is controlled by `closeOnClickOutside`. |
+| onEscape | `() => void` | no |  | Fires after Escape closes the popover. Notification only — does NOT govern whether close happens. That is controlled by `closeOnEscape`. |
+| onOpenChange | `(open: boolean) => void` | no |  | Fires when the popover opens or closes. |
+| onValueChange | `(value: Date | undefined) => void` | no |  | Fires when the selected date changes. |
+| placeholder | `string` | no |  | Placeholder when no date is selected. |
+| required | `boolean` | no | false | Mark input as required. |
+| showOutsideDays | `boolean` | no | true | Show days from adjacent months. |
+| showWeekNumbers | `boolean` | no | false | Show ISO week numbers. |
+| size | `'xs' | 'sm' | 'md' | 'lg' | 'xl'` | no | 'md' | Size variant that controls dimensions and spacing of the DatePicker |
+| value | `Date | string | null` | no |  | Currently selected date. Supports bind:value. Accepts a `Date`, an ISO timestamp string, or `null` / `undefined`. Internally coerced to a `Date`; the picker emits `Date` instances via . When both `bind:value` and `onValueChange` are wired, both fire on every user-driven change — pick one to drive side-effects (saves, analytics) to avoid duplicates. |
+| valueFormat | `'date' | 'iso'` | no | 'date' | Format used to serialise the date for the hidden form input. - `'date'` (default): `YYYY-MM-DD` in the local timezone — matches   the native `<input type="date">` payload and Zod schemas like   `z.string().regex(/^\d{4}-\d{2}-\d{2}$/).transform((v) => new Date(v))`. - `'iso'`: full ISO-8601 with `Z` suffix (UTC). Use this when the   downstream schema expects a parseable timestamp string (e.g. a   Drizzle `timestamp({ withTimezone: true, mode: 'date' })` column).  Only relevant when  is set. |
+| weekStartsOn | `WeekdayIndex` | no | 1 | First day of the week. 0 = Sunday, 1 = Monday. |
+
+Inherited from:
+- Omit<HTMLAttributes<HTMLDivElement>, 'children'> (omit-pattern)

package/content/blocks/components/donut-chart/llm.txt

@@ -0,0 +1,45 @@
+
+---
+
+## DonutChart
+Donut (or pie) chart for part-to-whole composition. Zero-
+dependency SVG arcs on the design-token palette, dark-mode aware, with an
+optional center total, legend, and a screen-reader data-table fallback. Set
+`innerRadiusRatio={0}` for a full pie. Pairs with CompositionBar for the
+linear equivalent.
+
+**Import:** `import { DonutChart } from '@urbicon-ui/blocks';`
+
+### Examples
+```svelte
+<DonutChart
+  data={[
+    { label: 'Direct', value: 45 },
+    { label: 'Referral', value: 30 },
+    { label: 'Organic', value: 25 }
+  ]}
+  showTotal
+/>
+```
+
+### Api
+| Prop | Type | Required | Default | Description |
+| --- | --- | :---: | --- | --- |
+| data | `DonutDatum[]` | yes |  | Slices; angle is each value's share of the total. |
+| ...HTMLAttributes<HTMLElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children') |
+| ariaLabel | `string` | no |  | Accessible label; a summary is generated when omitted. |
+| class | `string` | no |  | Extra classes merged onto the wrapper. |
+| formatValue | `(value: number) => string` | no |  | Format values for the center total, tooltips, and the data table. |
+| innerRadiusRatio | `number` | no | 0.6 | Inner-hole radius as a fraction of the outer radius (0 = pie). |
+| locale | `string` | no |  | BCP-47 locale for the default number formatter. |
+| padAngle | `number` | no | 0 | Gap between slices in degrees. |
+| preset | `string` | no |  | Apply a named preset registered on `<BlocksProvider>`. |
+| showLegend | `boolean` | no | true | ShowLegend property for the DonutChart component |
+| showTotal | `boolean` | no | false | Show the summed total in the center hole. |
+| size | `number` | no | 220 | Square SVG size in px. |
+| slotClasses | `ChartSlotClasses` | no |  | Per-slot class overrides. |
+| totalLabel | `string` | no |  | Caption under the center total (e.g. "Total"). |
+| unstyled | `boolean` | no |  | Remove all default tv classes. |
+
+Inherited from:
+- Omit<HTMLAttributes<HTMLElement>, 'children'> (omit-pattern)

package/content/blocks/components/empty-state/llm.txt

@@ -0,0 +1,43 @@
+
+---
+
+## EmptyState
+Centered placeholder block for "no data yet" / "no results"
+states. Pairs an optional icon with a heading, supporting text, and an
+optional call-to-action slot.
+
+**Import:** `import { EmptyState } from '@urbicon-ui/blocks';`
+
+### Examples
+```svelte
+<EmptyState
+  icon={BuildingIcon}
+  title="No apartments yet"
+  description="Get started by adding the first apartment to the system."
+>
+  {#snippet cta()}
+    <Button intent="primary" onclick={openCreate}>Add apartment</Button>
+  {/snippet}
+</EmptyState>
+```
+
+### Variants
+- density: compact, default (default: default)
+
+### Api
+| Prop | Type | Required | Default | Description |
+| --- | --- | :---: | --- | --- |
+| title | `string` | yes |  | Title property for the EmptyState component |
+| ...HTMLAttributes<HTMLDivElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children' | 'title') |
+| children | `Snippet` | no |  | Optional richer content rendered below the description (and replacing it visually). |
+| class | `string` | no |  | Extra classes merged onto the wrapper. |
+| cta | `Snippet` | no |  | Action buttons rendered below the description. |
+| density | `'compact' | 'default'` | no | 'default' | Visual density. `compact` is suitable for inline empty rows in tables or cards; `default` for full-page empty states. |
+| description | `string` | no |  | Supporting paragraph below the title. |
+| icon | `Component<IconProps>` | no |  | Icon component rendered above the title. Pass any icon from `@urbicon-ui/blocks/icons` (or a compatible stroke icon). |
+| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ EmptyState: {...} }}>`. Prefer this over `class` overrides when the same look should be reused across the project. |
+| slotClasses | `Partial<Record<EmptyStateSlot, string>>` | no |  | Per-slot class overrides. |
+| unstyled | `boolean` | no |  | Remove all default tv classes. |
+
+Inherited from:
+- Omit<HTMLAttributes<HTMLDivElement>, 'children' | 'title'> (omit-pattern)

package/content/blocks/components/file-upload/llm.txt

@@ -0,0 +1,76 @@
+
+---
+
+## FileUpload
+Drag-and-drop file upload with validation, image previews, progress tracking, and animated file list.
+
+**Import:** `import { FileUpload } from '@urbicon-ui/blocks';`
+
+### Examples
+```svelte
+<FileUpload
+  bind:files
+  multiple
+  maxFiles={5}
+  maxFileSize={10 * 1024 * 1024}
+  title="Drop files here or click to browse"
+  description="PDF, DOCX, XLSX — max 10 MB per file"
+/>
+```
+
+```svelte
+<FileUpload
+  bind:files
+  accept={IMAGE_MIME_TYPES}
+  multiple
+  maxFiles={8}
+  title="Upload images"
+  description="PNG, JPG, WebP — max 5 MB"
+  onFileReject={(rejections) => console.log('Rejected:', rejections)}
+/>
+```
+
+### Variants
+- intent: neutral, primary (default: neutral)
+- size: lg, md, sm (default: md)
+- disabled: false, true (default: false)
+
+### Api
+| Prop | Type | Required | Default | Description |
+| --- | --- | :---: | --- | --- |
+| ...FileUploadVariants | `VariantProps` | no |  | Styling variants from FileUploadVariants |
+| ...HTMLAttributes<HTMLDivElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children') |
+| accept | `string | string[]` | no |  | Accepted MIME types or file extensions (e.g. 'image/*', '.pdf'). |
+| allowDrop | `boolean` | no | true | Enable drag-and-drop. |
+| allowPaste | `boolean` | no | false | Enable paste from clipboard. |
+| children | `Snippet` | no |  | Default slot for fully custom dropzone content. |
+| class | `string` | no |  | Additional CSS class for the root element. |
+| description | `string` | no |  | Dropzone description text (accepted types, limits). |
+| disabled | `boolean` | no |  | Disable all interaction. |
+| dropzoneIcon | `Snippet` | no |  | Custom dropzone icon snippet. |
+| file | `File | null` | no |  | Convenience binding for single-file uses. Two-way: - Reads as `files[0]?.file ?? null`. - Setting to a `File` replaces the current selection (object URLs are   revoked, no validation re-runs — assumes the caller already validated). - Setting to `null` clears the list.  Recommended when `maxFiles === 1` (e.g. logo / avatar uploads). Use `bind:files` instead when you need progress, errors, or status metadata. |
+| fileItem | `Snippet<[FileItemContext]>` | no |  | Custom file item renderer. Receives file entry and remove callback. |
+| files | `FileUploadFile[]` | no |  | Current file list. Supports two-way binding. |
+| maxFiles | `number` | no |  | Maximum number of files. |
+| maxFileSize | `number` | no |  | Maximum file size in bytes. |
+| minFileSize | `number` | no |  | Minimum file size in bytes. |
+| mint | `MintProp` | no |  | Micro-interaction preset for the dropzone. |
+| multiple | `boolean` | no |  | Allow selecting multiple files. |
+| name | `string` | no |  | Shared `name` for native form submission. When set, the underlying hidden `<input type="file">` carries the current file list — including files added via drag/drop, paste, or programmatic `bind:files`, not just files picked through the file dialog. Submits as a `File[]` under `{name}` in the FormData payload. |
+| onFileAccept | `(files: FileUploadFile[]) => void` | no |  | Fires when valid files are accepted. |
+| onFileReject | `(rejections: FileRejection[]) => void` | no |  | Fires when files are rejected by validation. |
+| onFileRemove | `(file: FileUploadFile) => void` | no |  | Fires when a file is removed. |
+| onFilesChange | `(files: FileUploadFile[]) => void` | no |  | Fires when the file list changes (add or remove). |
+| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ FileUpload: {...} }}>`. Prefer this over `class` overrides when the requested look falls outside the semantic intent palette — presets keep hover/active/dark-mode logic coherent and make the custom look reusable across the project. |
+| preventDocumentDrop | `boolean` | no | true | Prevent browser navigation when files are dropped outside the zone. |
+| required | `boolean` | no |  | Mark as required for form validation. |
+| slotClasses | `Partial<Record<FileUploadSlotName, string>>` | no |  | Per-slot class overrides. |
+| title | `string` | no |  | Dropzone title text. |
+| unstyled | `boolean` | no |  | Strip all default styles. |
+| validate | `(file: File) => FileUploadError[] | null` | no |  | Custom validation function. Return errors array or null. |
+| intent | `'neutral' | 'primary'` | no | neutral | Controls the color theme and semantic meaning of the FileUpload. Affects the overall appearance and user perception. Available options: neutral, primary. |
+| size | `'lg' | 'md' | 'sm'` | no | md | Controls the dimensions, padding, and text size of the FileUpload. Affects the component's physical footprint. Available options: lg, md, sm. |
+
+Inherited from:
+- Omit<FileUploadVariants, 'dragging' | 'invalid'> (omit-pattern)
+- Omit<HTMLAttributes<HTMLDivElement>, 'children'> (omit-pattern)