alouette 20.0.0 → 20.0.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "alouette",
-  "version": "20.0.0",
+  "version": "20.0.1",
   "description": "A modern, customizable design system built on top of NativeWind v5 with configurable defaults",
   "keywords": [
     "tanstack-intent"
@@ -19,7 +19,8 @@
   "files": [
     "src",
     "dist",
-    "metro.cjs"
+    "metro.cjs",
+    "skills"
   ],
   "type": "module",
   "sideEffects": false,
@@ -47,6 +48,10 @@
         "import": "./dist/index-browser.es.js"
       }
     },
+    "./global.css": {
+      "style": "./src/global.css",
+      "default": "./src/global.css"
+    },
     "./metro.cjs": "./metro.cjs"
   },
   "dependencies": {
@@ -135,7 +140,8 @@
       }
     ],
     "extraEntries": [
-      "metro.cjs"
+      "metro.cjs",
+      "global.css"
     ],
     "jsx": true,
     "typescript": true

package/skills/alouette-actions/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: alouette-actions
+description: >
+  Buttons (Button, IconButton, ExternalLinkButton, InternalLinkButton) and
+  pressable surfaces (PressableBox, PressableListItem). variant is
+  contained|outlined|ghost, size is sm|md, accent defaults to brand. Button
+  label is the required text prop (not children); IconButton
+  requires aria-label. Interactive hover/focus/active/disabled states are built
+  in. Load when adding buttons or custom pressable elements.
+type: core
+library: alouette
+library_version: "20.0.0"
+requires:
+  - alouette-theming
+sources:
+  - "christophehurpeau/alouette:packages/alouette/src/ui/actions/Button.tsx"
+  - "christophehurpeau/alouette:packages/alouette/src/ui/actions/IconButton.tsx"
+  - "christophehurpeau/alouette:packages/alouette/src/ui/data/PressableBox.tsx"
+  - "christophehurpeau/alouette:packages/alouette/src/ui/data/PressableListItem.tsx"
+---
+
+This skill builds on alouette-theming. Read it first for the accent model.
+
+# alouette — Actions
+
+Buttons and pressables carry interactive token states (hover/focus/active/
+disabled) automatically. `variant` is `"contained" | "outlined" | "ghost"`;
+`size` is `"sm" | "md"`; `accent` defaults to `"brand"`.
+
+## Setup
+
+```tsx
+import { Button } from "alouette";
+import { CheckRegularIcon } from "alouette-icons/phosphor-icons/CheckRegularIcon";
+
+<Button text="Save" icon={<CheckRegularIcon />} onPress={save} />;
+```
+
+## Core Patterns
+
+### Button variants and accents
+
+```tsx
+<Button text="Save" />                                 {/* contained, brand */}
+<Button variant="outlined" text="Cancel" />
+<Button variant="ghost" text="Dismiss" />
+<Button accent="danger" text="Delete" />
+<Button size="sm" text="Small" />
+```
+
+### Icon-only button
+
+```tsx
+import { IconButton } from "alouette";
+import { XRegularIcon } from "alouette-icons/phosphor-icons/XRegularIcon";
+
+<IconButton icon={<XRegularIcon />} aria-label="Close" onPress={close} />;
+```
+
+`size` is `"sm" | "md"` or a number (custom diameter in px); `iconSize="fill"`
+makes the icon take 80% of the button.
+
+### Pressable surfaces
+
+`PressableBox` is a themed, pressable container (`variant`, `accent`,
+`forceStyle`). `PressableListItem` is a row with a trailing caret.
+
+```tsx
+import { PressableBox, PressableListItem, Text } from "alouette";
+
+<PressableBox onPress={open}>
+  <Text>Custom card</Text>
+</PressableBox>
+
+<PressableListItem onPress={open}>
+  <Text>Row label</Text>
+</PressableListItem>;
+```
+
+### Link buttons
+
+```tsx
+import { ExternalLinkButton, InternalLinkButton } from "alouette";
+
+<ExternalLinkButton href="https://example.com" text="Open" />
+<InternalLinkButton href="/settings" text="Settings" />
+```
+
+For full external-link control (in-app browser vs new tab), see
+alouette-external-links/SKILL.md.
+
+## Common Mistakes
+
+### HIGH Passing the button label as children instead of text
+
+Wrong:
+
+```tsx
+<Button>Save</Button>
+```
+
+Correct:
+
+```tsx
+<Button text="Save" />
+```
+
+`Button` renders its label from the required `text` prop (plus an optional `icon`
+prop); children are ignored, so `<Button>Save</Button>` shows no label.
+
+Source: packages/alouette/src/ui/actions/Button.tsx
+
+### HIGH Using non-existent variant names
+
+Wrong:
+
+```tsx
+<Button variant="ghost-contained" text="Cancel" />
+<Button variant="primary" text="Save" />
+```
+
+Correct:
+
+```tsx
+<Button variant="ghost" text="Cancel" />
+<Button accent="brand" text="Save" />
+```
+
+`variant` is only `"contained" | "outlined" | "ghost"`; the accent is chosen via
+the `accent` prop. (`ghost` is a variant value, not a separate boolean prop.)
+
+Source: packages/alouette/src/ui/data/PressableBox.tsx, ui/actions/Button.tsx
+
+### MEDIUM IconButton without aria-label
+
+Wrong:
+
+```tsx
+<IconButton icon={<XRegularIcon />} onPress={close} />
+```
+
+Correct:
+
+```tsx
+<IconButton icon={<XRegularIcon />} aria-label="Close" onPress={close} />
+```
+
+`IconButton` types `aria-label` as required because it has no text label;
+omitting it is an accessibility failure and a type error.
+
+Source: packages/alouette/src/ui/actions/IconButton.tsx

package/skills/alouette-animation/SKILL.md

@@ -0,0 +1,214 @@
+---
+name: alouette-animation
+description: >
+  Animate alouette UI two ways: NativeWind transitions (transition-*, duration-*,
+  ease-* on state changes like active:/hover:/focus:) and CSS keyframe presence
+  animations via PresenceOne / PresenceList (animate-slide-in/out,
+  animate-collapse-in/out). exitDurationMs must come from animationDurationsMs so
+  the unmount timer matches the keyframe. Both run on native via
+  react-native-reanimated. Load when adding transitions or enter/exit animations.
+type: core
+library: alouette
+library_version: "20.0.0"
+sources:
+  - "christophehurpeau/alouette:packages/alouette/src/ui/containers/Presence.tsx"
+  - "christophehurpeau/alouette:packages/alouette/src/animationDurationsMs.ts"
+  - "christophehurpeau/alouette:packages/alouette/src/ui/containers/Presence.stories.tsx"
+---
+
+# alouette — Animation
+
+alouette animates with plain CSS — no animation library in your code — and on
+native NativeWind v5 runs it through react-native-reanimated. There are two
+mechanisms:
+
+- **Transitions** — `transition-*` + `duration-*` + `ease-*` smooth a property
+  change driven by state (`active:`, `hover:`, `focus:`, theme/accent change).
+- **Presence (keyframes)** — `PresenceOne` / `PresenceList` play enter/exit
+  keyframe animations on mount/unmount (`animate-slide-in/out`,
+  `animate-collapse-in/out`), with durations from `animationDurationsMs`.
+
+## Transitions (state changes)
+
+State-change transitions (`transition-*` + `duration-*` + `ease-*`) are already
+built into alouette's interactive components. Use `InteractiveBox` (or
+`PressableBox`, `Button`, `IconButton`) — they animate press/hover/focus
+coherently (e.g. press scale plus background/border color) with the system's
+duration and easing. Don't reach for a raw react-native `Pressable`.
+
+```tsx
+import { InteractiveBox, Text } from "alouette";
+
+<InteractiveBox onPress={open} className="bg-surface rounded-sm p-m">
+  <Text>Animates on press / hover / focus</Text>
+</InteractiveBox>;
+```
+
+For a custom transition, add `transition-*` utilities on an alouette component
+that forwards `className` so it composes with the built-in ones:
+
+```tsx
+<InteractiveBox className="transition-[background-color] duration-200 ease-in hover:bg-lowered" />
+```
+
+## Presence: swap a single child
+
+```tsx
+import { PresenceOne, Box, Text, animationDurationsMs } from "alouette";
+
+function Swap({ step }: { step: number }) {
+  return (
+    <Box className="relative h-24 w-64">
+      <PresenceOne
+        activeKey={step}
+        exitDurationMs={animationDurationsMs.slide}
+        enterClassName="animate-slide-in"
+        exitClassName="animate-slide-out"
+        className="absolute inset-0 flex-center bg-surface rounded-md"
+      >
+        <Box>
+          <Text className="font-heading-bold text-2xl">Step {step}</Text>
+        </Box>
+      </PresenceOne>
+    </Box>
+  );
+}
+```
+
+## Core Patterns
+
+### Animated list (add / remove)
+
+Each child must have a stable `key`. Adding a key animates that item in; removing
+one animates only that item out before unmounting.
+
+```tsx
+import { PresenceList, InfoMessage, animationDurationsMs } from "alouette";
+
+<PresenceList
+  exitDurationMs={animationDurationsMs.collapse}
+  enterClassName="animate-collapse-in"
+  exitClassName="animate-collapse-out"
+  className="overflow-hidden"
+>
+  {items.map((item) => (
+    <InfoMessage
+      key={item.id}
+      onDismiss={() => remove(item.id)}
+      dismissIconAriaLabel="Dismiss"
+    >
+      {item.label}
+    </InfoMessage>
+  ))}
+</PresenceList>;
+```
+
+`PresenceOne` swaps a single child and merges the animation classes onto it via
+`cloneElement` (no wrapper); `PresenceList` wraps each child in its own `View`.
+
+## Common Mistakes
+
+### HIGH Hand-rolling transitions on a raw Pressable
+
+Wrong:
+
+```tsx
+import { Pressable } from "react-native";
+<Pressable className="transition-[transform] duration-200 active:scale-[0.975]">
+  {children}
+</Pressable>
+```
+
+Correct:
+
+```tsx
+import { InteractiveBox } from "alouette";
+<InteractiveBox onPress={open}>{children}</InteractiveBox>
+```
+
+alouette's interactive components already bundle press/hover/focus transitions
+with consistent duration and easing, plus disabled and focus-visible handling.
+Re-implementing them on a bare `Pressable` drifts from the system and misses
+that behavior.
+
+Source: packages/alouette/src/ui/containers/Box.tsx (InteractiveBox); ui/data/PressableBox.tsx
+
+### HIGH Hardcoding exitDurationMs instead of animationDurationsMs
+
+Wrong:
+
+```tsx
+<PresenceOne activeKey={id} exitDurationMs={600}
+  enterClassName="animate-slide-in" exitClassName="animate-slide-out">
+```
+
+Correct:
+
+```tsx
+import { animationDurationsMs } from "alouette";
+<PresenceOne activeKey={id} exitDurationMs={animationDurationsMs.slide}
+  enterClassName="animate-slide-in" exitClassName="animate-slide-out">
+```
+
+The unmount timer must equal the CSS keyframe duration. A hardcoded number drifts
+from the framework value, cutting the exit animation short or leaving ghost nodes
+mounted.
+
+Source: packages/alouette/src/animationDurationsMs.ts; ui/containers/Presence.stories.tsx
+
+### HIGH PresenceList children without stable keys
+
+Wrong:
+
+```tsx
+{items.map((it, i) => <InfoMessage key={i}>{it}</InfoMessage>)}
+```
+
+Correct:
+
+```tsx
+{items.map((it) => <InfoMessage key={it.id}>{it.label}</InfoMessage>)}
+```
+
+`PresenceList` diffs children by key to play add/remove animations. Index keys
+make removed items jump or skip their exit animation.
+
+Source: packages/alouette/src/ui/containers/Presence.tsx (usePresenceList)
+
+### MEDIUM PresenceOne child that doesn't forward className
+
+Wrong:
+
+```tsx
+<PresenceOne activeKey={id} exitDurationMs={animationDurationsMs.slide}>
+  <>{content}</>
+</PresenceOne>
+```
+
+Correct:
+
+```tsx
+<PresenceOne activeKey={id} exitDurationMs={animationDurationsMs.slide}
+  enterClassName="animate-slide-in" exitClassName="animate-slide-out">
+  <Box>{content}</Box>
+</PresenceOne>
+```
+
+`PresenceOne` merges the animation classes onto the child via `cloneElement`. A
+Fragment or a component that drops `className` gets no animation; use an alouette
+component (or one that forwards `className` to its root view).
+
+Source: packages/alouette/src/ui/containers/Presence.tsx (PresenceOne)
+
+### HIGH Expecting animations to run on native without reanimated
+
+Wrong: relying on the CSS animation while react-native-reanimated (and the
+`react-native-worklets/plugin` babel plugin) are not installed.
+
+Correct: install `react-native-reanimated` and add the worklets babel plugin, so
+NativeWind can run CSS transitions/animations on device.
+
+NativeWind v5 drives native animations through reanimated; without it, animations
+silently no-op on iOS/Android while still working on web.
+
+Source: packages/storybook-native-app/babel.config.js; packages/alouette/package.json (peerDependencies)

package/skills/alouette-external-links/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: alouette-external-links
+description: >
+  Open external URLs with ExternalLink (wraps expo-web-browser / Linking) or
+  ExternalLinkButton, configuring openLinkBehavior per platform (native:
+  linking|webBrowser; web: targetBlank|targetSelf). Load when linking out to
+  external URLs from alouette UI.
+type: composition
+library: alouette
+library_version: "20.0.0"
+requires:
+  - alouette-actions
+sources:
+  - "christophehurpeau/alouette:packages/alouette/src/expo/ExternalLink.tsx"
+  - "christophehurpeau/alouette:packages/alouette/src/ui/actions/Button.tsx"
+---
+
+This skill builds on alouette-actions. Read it first for button props.
+
+# alouette + expo-web-browser — External links
+
+`ExternalLink` centralizes outbound-URL behavior per platform: an in-app browser
+sheet (expo-web-browser) or `Linking` on native, and a new tab or same tab on
+web. `ExternalLinkButton` is the button shortcut for the common case.
+
+`ExternalOpenLinkBehavior`:
+`{ native: "linking" | "webBrowser"; web: "targetBlank" | "targetSelf" }`.
+
+## Setup
+
+```tsx
+import { ExternalLinkButton } from "alouette";
+
+<ExternalLinkButton href="https://example.com" text="Open docs" />;
+```
+
+## Core Patterns
+
+### Wrap any component with explicit per-platform behavior
+
+`ExternalLink` takes the target component via `as` and forwards remaining props.
+
+```tsx
+import { ExternalLink, Button } from "alouette";
+
+<ExternalLink
+  as={Button}
+  href="https://example.com"
+  openLinkBehavior={{ native: "webBrowser", web: "targetBlank" }}
+  text="Open"
+/>;
+```
+
+- `native: "webBrowser"` opens an in-app browser sheet themed with alouette colors.
+- `native: "linking"` hands off to the OS browser via `Linking.openURL`.
+- `web: "targetBlank"` opens a new tab; `"targetSelf"` navigates in place.
+
+## Common Mistakes
+
+### MEDIUM Calling Linking.openURL directly
+
+Wrong:
+
+```tsx
+import { Linking } from "react-native";
+<Pressable onPress={() => Linking.openURL(href)} />
+```
+
+Correct:
+
+```tsx
+<ExternalLink
+  as={Button}
+  href={href}
+  openLinkBehavior={{ native: "webBrowser", web: "targetBlank" }}
+  text="Open"
+/>
+```
+
+`ExternalLink` handles the in-app themed browser sheet on native and the correct
+target behavior on web; calling `Linking` directly loses both.
+
+Source: packages/alouette/src/expo/ExternalLink.tsx
+
+### MEDIUM Omitting openLinkBehavior
+
+Wrong:
+
+```tsx
+<ExternalLink as={Button} href={href} text="Open" />
+```
+
+Correct:
+
+```tsx
+<ExternalLink
+  as={Button}
+  href={href}
+  openLinkBehavior={{ native: "linking", web: "targetSelf" }}
+  text="Open"
+/>
+```
+
+`openLinkBehavior` is required and selects the native and web strategies; without
+it the link can't decide how to open and throws on an unsupported branch.
+(`ExternalLinkButton` defaults this for you — use it for the simple case.)
+
+Source: packages/alouette/src/expo/ExternalLink.tsx

package/skills/alouette-feedback/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: alouette-feedback
+description: >
+  Semantic message banners: Message (requires accent + icon) and the presets
+  InfoMessage, ConfirmationMessage, WarningMessage. Optional dismiss requires
+  onDismiss and dismissIconAriaLabel together; size is sm/md/lg. Load when
+  showing inline status, alerts, or dismissible notices.
+type: core
+library: alouette
+library_version: "20.0.0"
+requires:
+  - alouette-theming
+sources:
+  - "christophehurpeau/alouette:packages/alouette/src/ui/feedback/Message.tsx"
+  - "christophehurpeau/alouette:packages/alouette/src/ui/feedback/Message.stories.tsx"
+---
+
+This skill builds on alouette-theming. Read it first for the accent model.
+
+# alouette — Feedback messages
+
+`Message` is an accent-themed banner with an icon and optional dismiss button.
+Prefer the presets `InfoMessage` / `ConfirmationMessage` / `WarningMessage`,
+which set the accent and icon for you.
+
+## Setup
+
+```tsx
+import { InfoMessage } from "alouette";
+
+<InfoMessage>Your changes were saved.</InfoMessage>;
+```
+
+## Core Patterns
+
+### Presets
+
+```tsx
+import { InfoMessage, ConfirmationMessage, WarningMessage } from "alouette";
+
+<InfoMessage>Heads up.</InfoMessage>           {/* accent="info"    */}
+<ConfirmationMessage>Saved.</ConfirmationMessage> {/* accent="success" */}
+<WarningMessage>Careful.</WarningMessage>       {/* accent="warning" */}
+```
+
+### Dismissible message
+
+`onDismiss` and `dismissIconAriaLabel` must be provided together:
+
+```tsx
+<WarningMessage onDismiss={hide} dismissIconAriaLabel="Dismiss">
+  Low disk space.
+</WarningMessage>
+```
+
+### Custom Message (other accents / icons)
+
+For accents without a preset (e.g. `danger`), use the base `Message` with an
+explicit `accent` and `icon`. `size` is `"sm" | "md" | "lg"`.
+
+```tsx
+import { Message } from "alouette";
+import { XCircleRegularIcon } from "alouette-icons/phosphor-icons/XCircleRegularIcon";
+
+<Message accent="danger" icon={<XCircleRegularIcon />} size="lg">
+  Payment failed.
+</Message>;
+```
+
+## Common Mistakes
+
+### MEDIUM onDismiss without dismissIconAriaLabel
+
+Wrong:
+
+```tsx
+<InfoMessage onDismiss={hide}>Saved</InfoMessage>
+```
+
+Correct:
+
+```tsx
+<InfoMessage onDismiss={hide} dismissIconAriaLabel="Dismiss">
+  Saved
+</InfoMessage>
+```
+
+`Message` types `onDismiss` and `dismissIconAriaLabel` as a required pair;
+providing one without the other is a type error and leaves the dismiss button
+without an accessible label.
+
+Source: packages/alouette/src/ui/feedback/Message.tsx
+
+### MEDIUM Rendering the base Message without accent/icon
+
+Wrong:
+
+```tsx
+<Message>Heads up</Message>
+```
+
+Correct:
+
+```tsx
+<WarningMessage>Heads up</WarningMessage>
+```
+
+The base `Message` requires both `accent` and `icon`. For the common cases use a
+preset, which sets them.
+
+Source: packages/alouette/src/ui/feedback/Message.tsx
+
+### MEDIUM Hand-building a colored banner instead of Message
+
+Wrong:
+
+```tsx
+<Box className="bg-yellow-100"><Text>Warning</Text></Box>
+```
+
+Correct:
+
+```tsx
+<WarningMessage>Warning</WarningMessage>
+```
+
+A manual banner loses accent theming, the leading icon, dark-mode support and
+the dismiss a11y that `Message` provides.
+
+Source: packages/alouette/src/ui/feedback/Message.tsx
+
+See also: alouette-animation/SKILL.md — render messages in PresenceList for
+animated add/remove.