@tailor-platform/app-shell 1.18.0 → 1.20.0

package/skills/app-shell-patterns/references/api/aggregations.md

@@ -0,0 +1,131 @@
+---
+title: Value aggregations
+description: Reusable selector-based sum, average, minimum, maximum, and non-null count over row collections, with optional result-only transformation
+---
+
+<!-- GENERATED by docs-kit from docs-src/hooks/aggregations.docs.outline.md — do not edit by hand. -->
+
+# Value aggregations
+
+`aggregations` creates reusable callbacks that select values from a row collection and aggregate them. Each callback accepts `{ rows: readonly TRow[] }`; the module has no dependency on React, DataTable, or column definitions.
+
+```tsx
+import { aggregations, type Aggregation } from "@tailor-platform/app-shell";
+
+type Line = { quantity: number | null };
+
+const sum = aggregations.sum((row: Line) => row.quantity);
+sum({ rows: [{ quantity: 1 }, { quantity: 2 }, { quantity: null }] }); // 3
+sum({ rows: [{ quantity: 4 }, { quantity: 5 }] }); // 9: no previous aggregate state
+
+const summary: Aggregation<Line, string> = aggregations.sum(
+  (row: Line) => row.quantity,
+  (value) => (value === null ? "Unavailable" : `${value} units`),
+);
+summary({ rows: [{ quantity: 1 }, { quantity: 2 }] }); // "3 units"
+```
+
+## Operations
+
+| Factory                        | Result                                  | Empty or all-nullish selected values |
+| ------------------------------ | --------------------------------------- | ------------------------------------ |
+| `aggregations.sum(selector)`   | Sum of finite numbers                   | `0`                                  |
+| `aggregations.avg(selector)`   | Average of finite numbers               | `null`                               |
+| `aggregations.min(selector)`   | Minimum finite number                   | `null`                               |
+| `aggregations.max(selector)`   | Maximum finite number                   | `null`                               |
+| `aggregations.count(selector)` | Count of non-nullish values of any type | `0`                                  |
+
+A selector is required. It receives one row at a time and determines the values to aggregate. Numeric selectors must return `number | null | undefined`; count selectors may return any type. There is no automatic field lookup or connection to a column's `id`, `accessor`, or rendered content.
+
+Each factory returns an `Aggregation<TRow, TResult>` callback. Pass a read-only or mutable row array through `{ rows }`; aggregation does not mutate it or retain state between invocations. Selectors and transformers must be pure and must not mutate rows. Exceptions from either callback propagate to the caller.
+
+All operations skip selected `null` and `undefined` values. Numeric operations also validate selected values at runtime and return `null` for the entire result if any other value is not a finite JavaScript number, including numeric strings, booleans, dates, `NaN`, and infinities. They do not coerce values, compare dates or strings, or return a partial result. Average divides by the number of non-nullish numeric values, not the row count.
+
+Calculations use ordinary JavaScript numbers. A non-finite calculated result returns `null`; for average, this includes an intermediate sum overflow even when the mathematical average could be finite. These functions do not provide arbitrary-precision arithmetic.
+
+`count(selector)` counts selected `0`, `false`, and `""` as present values. It counts non-nullish values, not truthy values; use `rows.length` when every row should count.
+
+## Optional transformer
+
+Pass a second function to transform the final result:
+
+```tsx
+const averageText = aggregations.avg(
+  (row: Line) => row.quantity,
+  (value) => value?.toFixed(2) ?? "–",
+);
+averageText({ rows: [{ quantity: 1 }, { quantity: null }, { quantity: 2 }] }); // "1.50"
+
+const detailed = aggregations.sum(
+  (row: Line) => row.quantity,
+  (total) => ({ total, valid: total !== null }),
+);
+detailed({ rows: [{ quantity: 1 }, { quantity: 2 }] }); // { total: 3, valid: true }
+```
+
+The transformer is called exactly once per aggregation invocation, including for empty or invalid input. Numeric transformers receive `number | null`; count transformers receive `number`. Its return type becomes the callback's result type, and may be text, JSX, an object, or another value. The aggregation library does not interpret the transformed result.
+
+A transformer receives only the result, not rows, selected values, columns, or UI context. Filter `rows` before invoking the callback when the calculation needs a different input set.
+
+For detached callbacks, annotate the selector's row parameter as above so the row and transformed result types can both be inferred. Row types are not restricted to objects; for example, `aggregations.sum<number>((value) => value)({ rows: [1, 2] })` returns `3`.
+
+## Composing with business validation
+
+An aggregation is an ordinary callback, so a wrapper can validate the supplied rows before calling it. Keep business rules in the wrapper, numeric calculation in the aggregation, and result formatting in the transformer. The transformer is not an error handler: it receives `null` for invalid numeric results but has no row context or business-error details; selector exceptions still propagate.
+
+For example, reject mixed currencies before adding monetary amounts:
+
+```tsx
+type MoneyLine = { amount: number | null; currency: string };
+
+const sumAmount = aggregations.sum(
+  (row: MoneyLine) => row.amount,
+  (total) => (total === null ? "Invalid amount" : total.toLocaleString("en-US")),
+);
+
+const moneyFooter = (ctx: { rows: readonly MoneyLine[] }) => {
+  const currencies = new Set(
+    ctx.rows.filter((row) => row.amount != null).map((row) => row.currency),
+  );
+  if (currencies.size > 1) {
+    return `Mixed currencies: ${[...currencies].join(", ")}`;
+  }
+  return sumAmount(ctx);
+};
+
+moneyFooter({
+  rows: [
+    { amount: 1000, currency: "JPY" },
+    { amount: 500, currency: "JPY" },
+  ],
+}); // "1,500"
+moneyFooter({
+  rows: [
+    { amount: 1000, currency: "JPY" },
+    { amount: 500, currency: "USD" },
+  ],
+}); // "Mixed currencies: JPY, USD"
+```
+
+The guard ignores nullish amounts because they do not contribute to the sum. A rejected currency combination returns directly without evaluating the selector or transformer. Neither the wrapper nor the helper converts currencies or provides arbitrary-precision arithmetic.
+
+Pass `moneyFooter` directly as a column's `footer`. See the [runnable DataTable example](../components/data-table.md#composing-with-business-validation) to toggle mixed currencies and observe the composed behavior.
+
+## DataTable integration
+
+Pass an aggregation callback directly to a column footer. It is an ordinary footer renderer that reads the current `ctx.rows`; DataTable needs no aggregation-specific handling:
+
+```tsx
+import { aggregations, createColumnHelper } from "@tailor-platform/app-shell";
+
+const { column } = createColumnHelper<{ quantity: number | null }>();
+column({
+  id: "quantity",
+  type: "number",
+  footer: aggregations.sum((row) => row.quantity),
+});
+```
+
+Inline selectors infer the row type from the surrounding footer definition. The selector is the source of truth even when the column has an `accessor`; write the same calculation in the selector if the footer should aggregate a computed cell value.
+
+Use a transformer for simple footer text or JSX. DataTable only accepts callback results it can render; object-producing aggregations remain available for non-UI use. For the current-page scope, loading behavior, and custom renderers, see [DataTable column footers](../components/data-table.md#column-footers).

package/skills/app-shell-patterns/references/api/create-ai-gateway-client.md

@@ -7,7 +7,7 @@ description: Create a low-level AI Gateway client that reuses AppShell authentic
 
 # createAIGatewayClient
 
-Creates a small AI Gateway transport client for text-only chat completions.
+Creates a small AI Gateway transport client for chat completions and local function tool calls.
 
 ## Signature
 
@@ -43,6 +43,7 @@ interface AIGatewayClient {
 The iterable yields completion events:
 
 - `text-delta` — append `event.text` to build the assistant response
+- `tool-call` — a local function tool call requested by the model
 - `done` — terminal event with an optional `finishReason`
 
 ## Related Types
@@ -56,11 +57,33 @@ type AIGatewayChatMessage =
   | {
       role: "assistant";
       content?: string;
+      toolCalls?: AIGatewayToolCall[];
+    }
+  | {
+      role: "tool";
+      toolCallId: string;
+      content: string;
     };
 
+interface AIGatewayToolCall {
+  id: string;
+  name: string;
+  argumentsText: string;
+}
+
+interface AIGatewayFunctionTool {
+  type: "function";
+  function: {
+    name: string;
+    description?: string;
+    parameters: Record<string, unknown>;
+  };
+}
+
 interface AIGatewayChatRequest {
   model: string;
   messages: AIGatewayChatMessage[];
+  tools?: AIGatewayFunctionTool[];
   signal?: AbortSignal;
 }
 
@@ -69,6 +92,12 @@ type AIChatCompletionEvent =
       type: "text-delta";
       text: string;
     }
+  | {
+      type: "tool-call";
+      toolCallId: string;
+      toolName: string;
+      argumentsText: string;
+    }
   | {
       type: "done";
       finishReason?: string;
@@ -106,7 +135,8 @@ console.log(text);
 ## Notes
 
 - AppShell chooses the appropriate AI Gateway transport automatically
-- The low-level API is intentionally narrow: text deltas plus completion metadata
+- Local tools are sent as normalized `type: "function"` definitions; provider-native tools are not supported
+- The low-level API stays event-based so hooks can layer streaming UI and tool loops on top
 - `request.signal` is passed through so callers can abort in-flight work
 
 ## Related

package/skills/app-shell-patterns/references/api/define-module.md

@@ -100,11 +100,11 @@ A module object that can be passed to the `modules` prop of `AppShell`.
 ### Basic Module
 
 ```typescript
-import { defineModule } from "@tailor-platform/app-shell";
+import { defineModule, Text } from "@tailor-platform/app-shell";
 
 const dashboardModule = defineModule({
   path: "dashboard",
-  component: () => <h1>Dashboard</h1>,
+  component: () => <Text.h1>Dashboard</Text.h1>,
   resources: [],
 });
 ```
@@ -183,14 +183,14 @@ const adminModule = defineModule({
 ### Module with Error Boundary
 
 ```typescript
-import { useRouteError } from "@tailor-platform/app-shell";
+import { Text, useRouteError } from "@tailor-platform/app-shell";
 
 const ErrorBoundary = () => {
   const error = useRouteError() as Error;
   return (
     <div>
-      <h1>Module Error</h1>
-      <p>{error.message}</p>
+      <Text.h1>Module Error</Text.h1>
+      <Text.p>{error.message}</Text.p>
     </div>
   );
 };

package/skills/app-shell-patterns/references/api/router/use-params.md

@@ -182,7 +182,7 @@ function ProductEdit() {
 
   return (
     <form>
-      <h1>Edit Product {id}</h1>
+      <Text.h1>Edit Product {id}</Text.h1>
       {/* form fields */}
     </form>
   );
@@ -203,7 +203,7 @@ function DeleteConfirmation() {
 
   return (
     <div>
-      <p>Delete product {id}?</p>
+      <Text.p>Delete product {id}?</Text.p>
       <button onClick={handleDelete}>Confirm</button>
     </div>
   );

package/skills/app-shell-patterns/references/api/use-ai-chat.md

@@ -1,19 +1,24 @@
 ---
 title: useAIChat
-description: Simple text-only chat hook for AI Gateway
+description: AI Gateway chat hook with optional local tools
 ---
 
 <!-- GENERATED by docs-kit from docs-src/hooks/use-ai-chat.docs.outline.md — do not edit by hand. -->
 
 # useAIChat
 
-React hook for simple text-only chat on top of `createAIGatewayClient`.
+React hook for AI Gateway chat on top of `createAIGatewayClient`, with optional local tool support.
 
 ## Signature
 
 ```typescript
-const useAIChat: (config: { client: AIGatewayClient; model: string }) => {
+const useAIChat: (config: {
+  client: AIGatewayClient;
+  model: string;
+  tools?: Record<string, AILocalTool>;
+}) => {
   messages: AIChatMessage[];
+  toolCalls: { id: string; name: string }[];
   status: "ready" | "submitted" | "streaming" | "error";
   error?: Error;
   sendMessage: (message: string) => Promise<boolean>;
@@ -33,10 +38,17 @@ interface AIChatMessage {
 }
 ```
 
+### `toolCalls`
+
+- **Type:** `{ id: string; name: string }[]`
+- **Description:** Tool calls requested by the model in the active flow, including earlier tool rounds of the current request. This transient list is cleared when the response finishes, is stopped, or fails; it is never added to `messages` or conversation history.
+
+Calls become available before local tool execution. They record requested tool names, not successful execution. Arguments and results remain internal.
+
 ### `status`
 
 - **Type:** `"ready" | "submitted" | "streaming" | "error"`
-- **Description:** Current request state
+- **Description:** Current request state. `submitted` covers waiting for the first text, local tool execution, and waiting for the model's next reply after a tool result. `streaming` begins when text arrives. `AIChat.Conversation` automatically shows a waiting indicator while `submitted`.
 
 ### `error`
 
@@ -54,10 +66,20 @@ interface AIChatMessage {
 - **Type:** `() => void`
 - **Description:** Aborts the current request if one is in progress
 
+### `tools`
+
+Register local tools under a single object using `defineAIChatTool(...)`. Their schemas must implement both [Standard Schema](https://standardschema.dev/) validation and Standard JSON Schema generation (for example, Zod 4). Provider-native tools are not supported.
+
 ## Usage
 
 ```tsx
-import { createAuthClient, createAIGatewayClient, useAIChat } from "@tailor-platform/app-shell";
+import {
+  createAuthClient,
+  createAIGatewayClient,
+  defineAIChatTool,
+  useAIChat,
+} from "@tailor-platform/app-shell";
+import { z } from "zod/v4";
 
 const authClient = createAuthClient({
   clientId: "your-client-id",
@@ -69,10 +91,23 @@ const aiClient = createAIGatewayClient({
   authClient,
 });
 
+const lookupCustomer = defineAIChatTool({
+  description: "Look up a customer in the current workspace",
+  schema: z.object({
+    customerId: z.string(),
+  }),
+  async execute({ customerId }) {
+    return { customerId, name: "Acme Corp" };
+  },
+});
+
 export function ChatScreen() {
-  const { messages, sendMessage, status, stop, error } = useAIChat({
+  const { messages, toolCalls, sendMessage, status, stop, error } = useAIChat({
     client: aiClient,
     model: "gpt-5-mini",
+    tools: {
+      lookupCustomer,
+    },
   });
 
   return (
@@ -82,6 +117,9 @@ export function ChatScreen() {
           {message.role}: {message.content}
         </div>
       ))}
+      {toolCalls.map((call) => (
+        <div key={call.id}>Tool call: {call.name}</div>
+      ))}
 
       <button
         onClick={() => void sendMessage("Hello")}
@@ -101,9 +139,9 @@ export function ChatScreen() {
 ## Notes
 
 - AppShell chooses the appropriate AI Gateway transport automatically
-- The hook is intentionally text-only
+- Public messages stay user/assistant text-first; tool calls and results never become conversation messages
 - System prompts and custom history shaping should use the low-level client directly
-- `stop()` keeps any already-streamed assistant text and ignores late chunks from the stopped request
+- `stop()` keeps already-streamed assistant text, clears the active `toolCalls`, and ignores late events from the stopped request
 
 ## Related
 

package/skills/app-shell-patterns/references/api/use-app-shell-config.md

@@ -56,15 +56,15 @@ const useAppShellConfig: () => {
 ### Display App Info
 
 ```typescript
-import { useAppShellConfig } from "@tailor-platform/app-shell";
+import { Text, useAppShellConfig } from "@tailor-platform/app-shell";
 
 function AppInfo() {
   const { title, configurations } = useAppShellConfig();
 
   return (
     <div>
-      <h2>{title}</h2>
-      <p>Base: {configurations.basePath}</p>
+      <Text.h2>{title}</Text.h2>
+      <Text.p>Base: {configurations.basePath}</Text.p>
     </div>
   );
 }
@@ -96,7 +96,7 @@ function SettingsMenu() {
 
   return (
     <div>
-      <h3>Settings</h3>
+      <Text.h3>Settings</Text.h3>
       {configurations.settingsResources.map((resource) => (
         <button key={resource.path}>{resource.path}</button>
       ))}

package/skills/app-shell-patterns/references/api/use-app-shell-data.md

@@ -28,15 +28,15 @@ const useAppShellData: () => {
 ### Basic Access
 
 ```typescript
-import { useAppShellData } from "@tailor-platform/app-shell";
+import { Text, useAppShellData } from "@tailor-platform/app-shell";
 
 function UserProfile() {
   const { contextData } = useAppShellData();
 
   return (
     <div>
-      <p>Welcome, {contextData.currentUser?.name}</p>
-      <p>Role: {contextData.currentUser?.role}</p>
+      <Text.p>Welcome, {contextData.currentUser?.name}</Text.p>
+      <Text.p>Role: {contextData.currentUser?.role}</Text.p>
     </div>
   );
 }
@@ -54,8 +54,8 @@ function UserInfo() {
 
   return (
     <div>
-      <h2>{contextData.currentUser.name}</h2>
-      <p>{contextData.currentUser.email}</p>
+      <Text.h2>{contextData.currentUser.name}</Text.h2>
+      <Text.p>{contextData.currentUser.email}</Text.p>
     </div>
   );
 }

package/skills/app-shell-patterns/references/api/use-app-shell.md

@@ -120,8 +120,8 @@ function UserInfo() {
 
   return (
     <div>
-      <h2>{contextData.currentUser.name}</h2>
-      <p>{contextData.currentUser.email}</p>
+      <Text.h2>{contextData.currentUser.name}</Text.h2>
+      <Text.p>{contextData.currentUser.email}</Text.p>
     </div>
   );
 }

package/skills/app-shell-patterns/references/api/use-auth.md

@@ -59,7 +59,7 @@ const useAuth: () => {
 ### Basic Authentication Flow
 
 ```typescript
-import { useAuth } from "@tailor-platform/app-shell";
+import { Text, useAuth } from "@tailor-platform/app-shell";
 
 function MyComponent() {
   const { isAuthenticated, isReady, login, logout } = useAuth();
@@ -74,7 +74,7 @@ function MyComponent() {
 
   return (
     <div>
-      <p>You are logged in!</p>
+      <Text.p>You are logged in!</Text.p>
       <button onClick={logout}>Log Out</button>
     </div>
   );
@@ -108,7 +108,7 @@ function AuthStatus() {
   if (error) {
     return (
       <div>
-        <p>Authentication failed: {error}</p>
+        <Text.p>Authentication failed: {error}</Text.p>
         <button onClick={login}>Retry</button>
       </div>
     );

package/skills/app-shell-patterns/references/api/use-route-error.md

@@ -26,7 +26,7 @@ const useRouteError: () => unknown;
 ### Basic Error Boundary
 
 ```typescript
-import { useRouteError } from "@tailor-platform/app-shell";
+import { Text, useRouteError } from "@tailor-platform/app-shell";
 
 function ErrorBoundary() {
   const error = useRouteError();
@@ -37,8 +37,8 @@ function ErrorBoundary() {
 
   return (
     <div>
-      <h1>Something went wrong</h1>
-      <p>{message}</p>
+      <Text.h1>Something went wrong</Text.h1>
+      <Text.p>{message}</Text.p>
       <button onClick={() => window.location.reload()}>
         Try Again
       </button>
@@ -79,7 +79,7 @@ const productsModule = defineModule({
 ### Advanced Error Handling
 
 ```typescript
-import { isRouteErrorResponse, useRouteError } from "@tailor-platform/app-shell";
+import { isRouteErrorResponse, Text, useRouteError } from "@tailor-platform/app-shell";
 
 function ErrorBoundary() {
   const error = useRouteError();
@@ -88,8 +88,8 @@ function ErrorBoundary() {
   if (isRouteErrorResponse(error)) {
     return (
       <div>
-        <h1>{error.status} {error.statusText}</h1>
-        <p>{error.data}</p>
+        <Text.h1>{error.status} {error.statusText}</Text.h1>
+        <Text.p>{error.data}</Text.p>
       </div>
     );
   }
@@ -98,8 +98,8 @@ function ErrorBoundary() {
   if (error instanceof Error) {
     return (
       <div>
-        <h1>Error</h1>
-        <p>{error.message}</p>
+        <Text.h1>Error</Text.h1>
+        <Text.p>{error.message}</Text.p>
         <pre>{error.stack}</pre>
       </div>
     );
@@ -108,8 +108,8 @@ function ErrorBoundary() {
   // Handle unknown errors
   return (
     <div>
-      <h1>Unknown Error</h1>
-      <p>Something went wrong</p>
+      <Text.h1>Unknown Error</Text.h1>
+      <Text.p>Something went wrong</Text.p>
     </div>
   );
 }
@@ -129,8 +129,8 @@ function ErrorBoundary() {
 
   return (
     <div>
-      <h1>Error</h1>
-      <p>We've been notified and will fix this soon.</p>
+      <Text.h1>Error</Text.h1>
+      <Text.p>We've been notified and will fix this soon.</Text.p>
     </div>
   );
 }

package/skills/app-shell-patterns/references/components/action-panel.md

@@ -17,24 +17,30 @@ import { ActionPanel } from "@tailor-platform/app-shell";
 
 ## Basic Usage
 
+<example-preview name="basic-usage"></example-preview>
+
 ```tsx
-<ActionPanel
-  title="Actions"
-  actions={[
-    {
-      key: "create-invoice",
-      label: "Create new sales invoice",
-      icon: <ReceiptIcon />,
-      onClick: () => openCreateInvoiceModal(),
-    },
-    {
-      key: "view-docs",
-      label: "View documentation",
-      icon: <ExternalLinkIcon />,
-      onClick: () => window.open("/docs", "_blank", "noopener,noreferrer"),
-    },
-  ]}
-/>
+function BasicUsage() {
+  return (
+    <ActionPanel
+      title="Actions"
+      actions={[
+        {
+          key: "create-invoice",
+          label: "Create new sales invoice",
+          icon: <Receipt />,
+          onClick: () => {},
+        },
+        {
+          key: "view-docs",
+          label: "View documentation",
+          icon: <ExternalLink />,
+          onClick: () => {},
+        },
+      ]}
+    />
+  );
+}
 ```
 
 ## Props
@@ -43,11 +49,12 @@ _Generated from the type surface — first-party props only._
 
 ### ActionPanelProps
 
-| Prop         | Type           | Default | Description                                   |
-| ------------ | -------------- | ------- | --------------------------------------------- |
-| `actions`    | `ActionItem[]` | -       | List of actions to render                     |
-| `className?` | `string`       | -       | Additional CSS classes for the card container |
-| `title`      | `string`       | -       | Card title                                    |
+| Prop            | Type           | Default | Description                                                                                                                                                                                                                                                                                                   |
+| --------------- | -------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `actions`       | `ActionItem[]` | -       | List of actions to render                                                                                                                                                                                                                                                                                     |
+| `className?`    | `string`       | -       | Additional CSS classes for the card container                                                                                                                                                                                                                                                                 |
+| `emptyContent?` | `ReactNode`    | -       | Content shown with consistent padding when actions is empty. Defaults to a localized "No actions available" message. Strings use the default body text styling; other React nodes render unchanged. Pass null to hide the empty content and its additional vertical spacing while keeping the card and title. |
+| `title`         | `string`       | -       | Card title                                                                                                                                                                                                                                                                                                    |
 
 ## Exports
 
@@ -71,7 +78,34 @@ _Generated from the type surface — first-party props only._
 - Rows are rendered as `<button type="button">` elements.
 - `disabled` or `loading` makes the row non-interactive.
 - When `loading` is `true`, the icon slot renders a spinner without shifting layout.
-- Empty actions show a built-in fallback message: `No actions available`.
+- Empty actions show `emptyContent`, which defaults to a styled message localized using the AppShell locale: `No actions available` in English or `利用可能なアクションはありません` in Japanese.
+
+## Custom Empty Content
+
+Pass a string or any `ReactNode` to `emptyContent` to replace the default content when `actions` is empty. Strings use the same muted `Text` body styling as the default message. Other React nodes render directly inside `Card.Content` without a paragraph wrapper and control their own typography. `Card.Content` owns the spacing, and the title, empty content, and action icons share the same 32px horizontal inset. Action rows retain horizontal padding around their hover backgrounds and focus rings. Custom empty content is ignored when actions are present.
+
+<example-preview name="custom-empty-content"></example-preview>
+
+```tsx
+function CustomEmptyContent() {
+  return (
+    <ActionPanel
+      title="操作"
+      actions={[]}
+      emptyContent={
+        <div>
+          <Text.p className="text-muted-foreground">利用可能な操作はありません</Text.p>
+          <Text.p className="text-muted-foreground">
+            ステータスが変わると、操作が表示されます。
+          </Text.p>
+        </div>
+      }
+    />
+  );
+}
+```
+
+Pass `null` to hide the empty content and its additional vertical spacing while keeping the card and its title. To hide the entire panel when no actions are available, render it conditionally with `actions.length > 0`.
 
 ## With Loading State
 

package/skills/app-shell-patterns/references/components/activity-card.md

@@ -105,7 +105,7 @@ import { ActivityCard, type ActivityCardBaseItem } from "@tailor-platform/app-sh
 ### Example
 
 ```tsx
-import { ActivityCard, type ActivityCardBaseItem } from "@tailor-platform/app-shell";
+import { ActivityCard, Text, type ActivityCardBaseItem } from "@tailor-platform/app-shell";
 
 interface MyItem extends ActivityCardBaseItem {
   kind: "approval" | "update";
@@ -123,11 +123,11 @@ const items: MyItem[] = [
     {(item) =>
       item.kind === "approval" ? (
         <ActivityCard.Item indicator={<ApprovedIcon />}>
-          <p>{item.label}</p>
+          <Text.p>{item.label}</Text.p>
         </ActivityCard.Item>
       ) : (
         <ActivityCard.Item>
-          <p>{item.message}</p>
+          <Text.p>{item.message}</Text.p>
         </ActivityCard.Item>
       )
     }