@tcn/ui 0.18.0 → 0.18.1

package/ai-docs/tokens.md

@@ -0,0 +1,35 @@
+# Tokens
+
+> **Scaffold placeholder.** Read the source files below for full implementation details. This document will be expanded with usage patterns and examples.
+
+---
+
+## Source Files
+
+| File | Purpose |
+|---|---|
+| `src/tokens/chip/chip.tsx` | Selectable chip/tag |
+| `src/tokens/badge/badge.tsx` | Badge indicator |
+| `src/tokens/bubble/bubble.tsx` | Bubble/pill token |
+| `src/tokens/key/key.tsx` | Keyboard key display |
+| `src/tokens/value/value.tsx` | Value display token |
+| `src/tokens/term/term.tsx` | Key-value term container |
+
+---
+
+## Imports
+
+```ts
+import { Chip, Badge, Bubble, Key, Value, Term } from '@tcn/ui/tokens';
+```
+
+---
+
+## Quick Reference
+
+- `Chip` is a selectable tag (filter chips, choice chips)
+- `Badge` is a small indicator overlay (counts, status dots)
+- `Bubble` is a pill-shaped text container
+- `Key` displays a keyboard key (for shortcut hints)
+- `Value` displays a formatted value
+- `Term` pairs a key label with a value (key-value display)

package/ai-docs/typography.md

@@ -0,0 +1,38 @@
+# Typography
+
+> **Scaffold placeholder.** Read the source files below for full implementation details. This document will be expanded with usage patterns and examples.
+
+---
+
+## Source Files
+
+| File | Purpose |
+|---|---|
+| `src/typography/headline/headline.tsx` | Large heading text |
+| `src/typography/title/title.tsx` | Title text |
+| `src/typography/subheadline/subheadline.tsx` | Subheading text |
+| `src/typography/body_text/body_text.tsx` | Body paragraph text |
+| `src/typography/caption/caption.tsx` | Small caption text |
+| `src/typography/callout/callout.tsx` | Highlighted callout text |
+| `src/typography/footnote/footnote.tsx` | Footnote text |
+
+---
+
+## Imports
+
+```ts
+import {
+  Headline, Title, Subheadline,
+  BodyText, Caption, Callout, Footnote,
+} from '@tcn/ui/typography';
+```
+
+---
+
+## Quick Reference
+
+- Typography components define semantic text roles, not visual sizes — themes control appearance
+- Hierarchy (largest to smallest): Headline > Title > Subheadline > BodyText > Caption > Footnote
+- `Callout` is for highlighted/emphasized text blocks
+- All typography uses the polymorphic `as` prop to render as the correct HTML element
+- Font family, size, weight, and color come from theme variables

package/ai-docs/utils.md

@@ -0,0 +1,51 @@
+# Utilities
+
+> **Scaffold placeholder.** Read the source files below for full implementation details. This document will be expanded with usage patterns and examples.
+
+---
+
+## Source Files
+
+| File | Purpose |
+|---|---|
+| `src/utils/hooks/use_fork_ref.ts` | Compose multiple refs into one |
+| `src/utils/hooks/use_resize_observer.ts` | Track element resize events |
+| `src/utils/hooks/use_media_query.ts` | React hook for CSS media queries |
+| `src/utils/hooks/make_context_hook.ts` | Factory for typed context hooks |
+| `src/utils/listeners/` | Event listener utilities |
+| `src/utils/calendar/` | Date utilities (CalendarDate, month generators) |
+| `src/utils/types/` | Shared type definitions (Dimensions, Sides) |
+| `src/utils/system/` | System-level utilities |
+| `src/utils/default_value.ts` | Default value handling |
+| `src/utils/css_utils.ts` | CSS utility functions |
+
+---
+
+## Imports
+
+```ts
+import {
+  useForkRef, useResizeObserver, useMediaQuery,
+  makeContextHook,
+} from '@tcn/ui/utils';
+
+// Calendar utilities
+import {
+  CalendarDate, CalendarDatesGenerator,
+  getMonthsOfYear, getDaysOfWeek,
+} from '@tcn/ui/utils';
+
+// Decorators (see ai-docs/decorators.md)
+import { Draggable, DragHandle, Resizable } from '@tcn/ui/utils';
+```
+
+---
+
+## Quick Reference
+
+- `useForkRef` composes multiple refs — essential for `forwardRef` + internal ref
+- `useResizeObserver` tracks element dimensions reactively
+- `useMediaQuery` evaluates CSS media queries in React
+- `makeContextHook` creates typed context hooks with descriptive error messages
+- Calendar utilities power the DatePicker (not general-purpose date libraries)
+- For decorators (Draggable, Resizable), see [decorators.md](decorators.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tcn/ui",
-  "version": "0.18.0",
+  "version": "0.18.1",
   "type": "module",
   "description": "",
   "author": "TCN",
@@ -21,6 +21,10 @@
     "src",
     "types",
     "README.md",
+    "CHANGELOG.md",
+    "AI_USAGE.md",
+    "ai-docs",
+    "!ai-docs/*.local.md",
     "tsconfig.json"
   ],
   "sideEffects": [
@@ -138,7 +142,7 @@
     "react-color": "^2.19.3",
     "react-phone-number-input": "^3.4.16",
     "@tcn/icons": "2.4.0",
-    "@tcn/state": "1.3.3"
+    "@tcn/state": "1.3.4"
   },
   "scripts": {
     "build": "vite build",

package/src/overlay/popper/legacy/popper.stories.tsx

@@ -97,8 +97,15 @@ export function Popper(props: PopoverStoryProps) {
   }
 
   return (
-    <VStack height="100%" width="100%" minHeight="600px" hAlign="center" vAlign="center">
-      <button onClick={open}>Open</button>
+    <VStack
+      height="100%"
+      width="100%"
+      minHeight="600px"
+      hAlign="center"
+      vAlign="center"
+      style={{ display: 'flex', alignItems: 'flex-end' }}
+    >
+      <button onClick={open}>Open me</button>
       <PopperComponent
         anchorElement={anchorElement}
         open={isOpen}