@ankhorage/zora 2.5.1 → 2.5.2

package/src/components/button/Button.tsx

@@ -20,4 +20,16 @@ function ButtonInner({
   );
 }
 
+/***
+ * Theme-aware action control for primary, secondary, destructive, and neutral actions.
+ *
+ * Use `Button` for explicit user actions that should follow ZORA's semantic color,
+ * variant, and size recipes across React Native and React Native Web.
+ *
+ * @readme
+ * @example Basic action
+ * ```tsx
+ * <Button color="primary" variant="solid" onPress={save}>Save</Button>
+ * ```
+ */
 export const Button = withZoraThemeScope(ButtonInner);

package/src/components/card/Card.tsx

@@ -70,4 +70,16 @@ function CardInner({
   );
 }
 
+/***
+ * Structured content container with built-in heading, description, actions, and footer slots.
+ *
+ * Use `Card` for reusable content blocks that should inherit ZORA spacing,
+ * radius, tone, and responsive header layout without hand-assembling primitives.
+ *
+ * @readme
+ * @example Content card
+ * ```tsx
+ * <Card title="Project" description="Latest activity">...</Card>
+ * ```
+ */
 export const Card = withZoraThemeScope(CardInner);

package/src/components/heading/Heading.tsx

@@ -91,4 +91,16 @@ function HeadingInner({
   );
 }
 
+/***
+ * Structured title primitive for accessible page, section, and card headings.
+ *
+ * `Heading` gives consumers a ZORA-owned title API with semantic levels,
+ * responsive sizes, and theme-aware emphasis while preserving header semantics.
+ *
+ * @readme
+ * @example Section title
+ * ```tsx
+ * <Heading level={2} size="xl">Account settings</Heading>
+ * ```
+ */
 export const Heading = withZoraThemeScope(HeadingInner);

package/src/components/input/Input.tsx

@@ -62,4 +62,16 @@ function InputInner({
   );
 }
 
+/***
+ * Theme-aware text input with semantic sizing and optional leading/trailing icon slots.
+ *
+ * Use `Input` for single-line form controls that need ZORA styling, disabled/read-only
+ * handling, and accessible trailing actions without dropping into Surface directly.
+ *
+ * @readme
+ * @example Search input
+ * ```tsx
+ * <Input placeholder="Search" leadingIcon={{ name: 'search-outline' }} />
+ * ```
+ */
 export const Input = withZoraThemeScope(InputInner);

package/src/components/text/Text.tsx

@@ -88,4 +88,16 @@ function TextInner({
   );
 }
 
+/***
+ * Structured copy primitive for theme-aware app text.
+ *
+ * `Text` owns normal body, caption, label, code, and supporting-copy variants so
+ * consumers do not need to import lower-level Surface typography directly.
+ *
+ * @readme
+ * @example Muted supporting copy
+ * ```tsx
+ * <Text variant="bodySmall" emphasis="muted">Updated just now</Text>
+ * ```
+ */
 export const Text = withZoraThemeScope(TextInner);

package/src/layout/app-shell/AppShell.tsx

@@ -33,6 +33,18 @@ function AppShellInner({
   );
 }
 
+/***
+ * Root application shell with stable header, content, footer, and overlay slots.
+ *
+ * `AppShell` provides the top-level layout frame for cross-platform apps while
+ * leaving navigation, toolbars, and overlays composable through explicit slots.
+ *
+ * @readme
+ * @example App frame
+ * ```tsx
+ * <AppShell header={<AppBar title="Dashboard" />}>...</AppShell>
+ * ```
+ */
 export const AppShell = withZoraThemeScope(AppShellInner);
 
 const styles = StyleSheet.create({

package/src/patterns/empty-state/EmptyState.tsx

@@ -55,4 +55,16 @@ function EmptyStateInner({
   );
 }
 
+/***
+ * Reusable fallback state for empty lists, missing data, or first-run experiences.
+ *
+ * `EmptyState` combines concise copy with optional primary and secondary actions
+ * so apps can guide users without custom card and button wiring.
+ *
+ * @readme
+ * @example Empty project list
+ * ```tsx
+ * <EmptyState title="No projects yet" primaryAction={{ label: 'Create project', onPress }} />
+ * ```
+ */
 export const EmptyState = withZoraThemeScope(EmptyStateInner);

package/src/patterns/responsive-panel/ResponsivePanel.tsx

@@ -144,4 +144,16 @@ const styles = StyleSheet.create({
   },
 });
 
+/***
+ * Adaptive secondary surface that can render as an inline panel, drawer, or modal.
+ *
+ * Use `ResponsivePanel` for tool panes and admin/detail flows that need the same
+ * content to work across compact mobile screens and wider desktop layouts.
+ *
+ * @readme
+ * @example Scrollable wide panel
+ * ```tsx
+ * <ResponsivePanel open title="APIs" size="wide" scroll="content">...</ResponsivePanel>
+ * ```
+ */
 export const ResponsivePanel = withZoraThemeScope(ResponsivePanelInner);

package/src/theme/ZoraProvider.tsx

@@ -12,6 +12,18 @@ export interface ZoraProviderProps {
   initialMode?: ZoraThemeMode;
 }
 
+/***
+ * Installs the ZORA theme runtime and underlying Surface theme provider.
+ *
+ * Wrap an app with `ZoraProvider` once near the root so components, patterns,
+ * layouts, and theme hooks resolve the same design tokens and color mode.
+ *
+ * @readme
+ * @example App provider
+ * ```tsx
+ * <ZoraProvider initialMode="light"><App /></ZoraProvider>
+ * ```
+ */
 export function ZoraProvider({
   children,
   theme = zoraDefaultTheme,