@spark-web/text 0.0.0-snapshot-release-20260409001813

package/CLAUDE.md

@@ -0,0 +1,91 @@
+# @spark-web/text — AI Context
+
+## What this is
+
+The primary text rendering component. Applies theme typography tokens (size,
+weight, tone, baseline trimming) and renders as a block `div` by default. Use
+for body copy, labels, captions, status messages, and cell content inside
+tables.
+
+## What this is NOT
+
+- Not a heading — use `@spark-web/heading` for semantic headings (h1–h4)
+- Not a link — use `@spark-web/text-link` for anchor text
+- Not a layout container — do not put layout logic inside `Text`
+
+## Props interface
+
+| Prop               | Type                                                                                                                                                                                                                                                                                            | Default      | Notes                                                                                              |
+| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ | -------------------------------------------------------------------------------------------------- |
+| `size`             | `'xsmall' \| 'small' \| 'standard' \| 'large'`                                                                                                                                                                                                                                                  | `'standard'` | Typography scale                                                                                   |
+| `tone`             | `'neutral' \| 'muted' \| 'link' \| 'disabled' \| 'field' \| 'fieldAccent' \| 'placeholder' \| 'accent' \| 'primary' \| 'primaryHover' \| 'primaryActive' \| 'secondary' \| 'secondaryHover' \| 'secondaryActive' \| 'caution' \| 'critical' \| 'info' \| 'positive' \| 'dark' \| 'brandSubtle'` | `'neutral'`  | Text color                                                                                         |
+| `weight`           | `'regular' \| 'semibold'`                                                                                                                                                                                                                                                                       | —            | Font weight override                                                                               |
+| `align`            | `'left' \| 'center' \| 'right'`                                                                                                                                                                                                                                                                 | —            | Block variant only (not compatible with `inline`)                                                  |
+| `inline`           | `boolean`                                                                                                                                                                                                                                                                                       | `false`      | Renders as `<span>` with `display: inline`                                                         |
+| `baseline`         | `boolean`                                                                                                                                                                                                                                                                                       | `true`       | Apply leading-trim (cap-height) — set `false` when not adjacent to other baseline-trimmed elements |
+| `overflowStrategy` | `'truncate' \| 'nowrap'`                                                                                                                                                                                                                                                                        | —            | Block variant only                                                                                 |
+| `numberOfLines`    | `number`                                                                                                                                                                                                                                                                                        | —            | Clamp to N lines with ellipsis                                                                     |
+| `tabularNumbers`   | `boolean`                                                                                                                                                                                                                                                                                       | `false`      | Monospace-width numerals                                                                           |
+| `transform`        | CSS `textTransform` value                                                                                                                                                                                                                                                                       | —            | `'uppercase'`, `'capitalize'`, etc.                                                                |
+| `as`               | HTML element tag                                                                                                                                                                                                                                                                                | `'div'`      | Use `'span'`, `'p'`, `'label'`, etc. as needed                                                     |
+| `data`             | `DataAttributeMap`                                                                                                                                                                                                                                                                              | —            | Test/analytics attributes                                                                          |
+
+## Token usage
+
+All typography values come from `theme.typography`. Text internally uses
+`useText()` which maps `size` → responsive font-size/line-height and applies
+baseline trimming. Never compute font sizes or colors directly — always use
+`Text` props.
+
+## Common patterns
+
+### Table cell content
+
+```tsx
+// Always size="small" in table cells
+<Text size="small">{row.name}</Text>
+```
+
+### Muted supporting text
+
+```tsx
+<Text tone="muted" size="small">
+  No records found
+</Text>
+```
+
+### Inline label within a block
+
+```tsx
+<Text>
+  Status:{' '}
+  <Text inline tone="positive">
+    Active
+  </Text>
+</Text>
+```
+
+### Truncate long values
+
+```tsx
+<Text size="small" overflowStrategy="truncate">
+  {longValue}
+</Text>
+```
+
+## Composition
+
+`Text` renders a `Box` internally. It provides a `TextContext` so nested `Text`
+components inherit `size`, `tone`, and `weight` — override only what differs
+from the parent.
+
+## Do NOTs
+
+- NEVER use raw CSS for font-size, color, or line-height — always use `Text`
+  props
+- NEVER use `tone="neutralInverted"` or `tone="mutedInverted"` directly — these
+  are automatic inversions applied by the `background` context
+- NEVER set `baseline={true}` (the default) on a `Text` that is not inside a
+  layout component that accounts for leading-trim — set `baseline={false}` when
+  in doubt for non-standard layouts
+- NEVER use `Text` for headings — use `@spark-web/heading`

package/README.md

@@ -0,0 +1,145 @@
+---
+title: Text
+storybookPath: typography-text--default
+isExperimentalPackage: false
+---
+
+Constrained, purposeful text styles as a component.
+
+## Examples
+
+```jsx live
+const textSizes = ['large', 'standard', 'small', 'xsmall'];
+
+return (
+  <Columns collapseBelow="tablet" gap="xlarge">
+    <Stack gap="large">
+      {textSizes.map(textSize => (
+        <Text key={textSize} size={textSize} weight="regular">
+          Text {textSize} regular
+        </Text>
+      ))}
+    </Stack>
+    <Stack gap="large">
+      {textSizes.map(textSize => (
+        <Text key={textSize} size={textSize} weight="semibold">
+          Text {textSize} regular
+        </Text>
+      ))}
+    </Stack>
+  </Columns>
+);
+```
+
+### Align
+
+Text can be aligned with the `align` prop.
+
+```jsx live
+<Stack gap="large" dividers>
+  <Text align="left">Left (default)</Text>
+  <Text align="center">Center</Text>
+  <Text align="right">Right</Text>
+</Stack>
+```
+
+### Overflow strategy
+
+Use the `overflowStrategy` prop to manage how `Text` behaves with regard to
+overflow.
+
+```jsx live
+const overflowStrategies = ['truncate', 'nowrap', 'breakword'];
+
+return (
+  <Stack gap="large" style={{ width: 200 }}>
+    <Stack gap="small">
+      <Text weight="semibold">Default</Text>
+      <Text>The quick brown fox jumps over the lazy dog.</Text>
+    </Stack>
+    {overflowStrategies.map(overflowStrategy => (
+      <Stack key={overflowStrategy} gap="small">
+        <Text weight="semibold">{overflowStrategy}</Text>
+        <Text overflowStrategy={overflowStrategy}>
+          The quick brown fox jumps over the lazy dog.
+        </Text>
+      </Stack>
+    ))}
+  </Stack>
+);
+```
+
+### Tone
+
+The foreground colour of text can be set by applying a `tone`. In addition to
+the foundation tones, “muted” provides a way to de-emphasise text.
+
+```jsx live
+const textTones = [
+  'neutral', // Default
+  'accent',
+  'caution',
+  'critical',
+  'disabled',
+  'fieldAccent',
+  'info',
+  'link',
+  'muted',
+  'placeholder',
+  'positive',
+  'primary',
+  'primaryActive',
+  'primaryHover',
+  'secondary',
+  'secondaryActive',
+  'secondaryHover',
+];
+
+return (
+  <Columns collapseBelow="tablet" gap="large" template={[1, 1]}>
+    {textTones.map(tone => (
+      <Text key={tone} tone={tone}>
+        {tone}
+      </Text>
+    ))}
+  </Columns>
+);
+```
+
+### Weight
+
+Text is available in two weight: `regular` and `semibold`.
+
+```jsx live
+<Inline gap="small">
+  <Text weight="regular">Regular</Text>
+  <Text weight="semibold">Semibold</Text>
+</Inline>
+```
+
+### Contrast
+
+To ensure text has sufficient contrast, when on a dark background the foreground
+tones “neutral” and “muted” will be inverted.
+
+```jsx live
+<Inline gap="large">
+  <Box background="neutral" padding="small" borderRadius="small">
+    <Text>neutral</Text>
+  </Box>
+  <Box background="neutral" padding="small" borderRadius="small">
+    <Text tone="muted">muted</Text>
+  </Box>
+</Inline>
+```
+
+## Props
+
+<PropsTable displayName="Text" />
+
+Extra props are also passed into the underlying [`Box`](/package/box) component.
+
+[brighte-theme]:
+  https://github.com/brighte-labs/spark-web/blob/e503bea4f7668d187ec7a78f99c5ed374417588b/packages/theme/src/makeTheme.ts#L158
+[data-attribute-map]:
+  https://github.com/brighte-labs/spark-web/blob/e7f6f4285b4cfd876312cc89fbdd094039aa239a/packages/utils/src/internal/buildDataAttributes.ts#L1

package/dist/declarations/src/context.d.ts

@@ -0,0 +1,10 @@
+export declare const TextContext: import("react").Context<{
+    size: NonNullable<import("@spark-web/theme/src/themes/_types/typography").TypographySizing>;
+    tone: NonNullable<string | number>;
+    weight: NonNullable<"bold" | "medium" | "light" | "thin" | "black" | "extralight" | "regular" | "semibold" | "extrabold" | undefined> | undefined;
+} | undefined>;
+export declare function useTextContext(): {
+    size: NonNullable<import("@spark-web/theme/src/themes/_types/typography").TypographySizing>;
+    tone: NonNullable<string | number>;
+    weight: NonNullable<"bold" | "medium" | "light" | "thin" | "black" | "extralight" | "regular" | "semibold" | "extrabold" | undefined> | undefined;
+} | undefined;

package/dist/declarations/src/default-text-props.d.ts

@@ -0,0 +1,16 @@
+import type { ReactNode } from 'react';
+import type { UseTextProps } from "./use-text.js";
+type DefaultTextProps = {
+    size?: NonNullable<UseTextProps['size']>;
+    tone?: NonNullable<UseTextProps['tone']>;
+    weight?: NonNullable<UseTextProps['weight']>;
+};
+export declare function DefaultTextPropsProvider({ children, size, tone, weight, }: DefaultTextProps & {
+    children: ReactNode;
+}): import("@emotion/react/jsx-runtime").JSX.Element;
+export declare const useDefaultTextProps: ({ size: sizeProp, tone: toneProp, weight: weightProp, }: DefaultTextProps) => {
+    size: NonNullable<import("@spark-web/theme/src/themes/_types/typography").TypographySizing>;
+    tone: NonNullable<string | number>;
+    weight: NonNullable<"bold" | "medium" | "light" | "thin" | "black" | "extralight" | "regular" | "semibold" | "extrabold" | undefined> | undefined;
+};
+export {};

package/dist/declarations/src/index.d.ts

@@ -0,0 +1,12 @@
+export { useTextContext } from "./context.js";
+export { DefaultTextPropsProvider, useDefaultTextProps, } from "./default-text-props.js";
+export { Strong } from "./strong.js";
+export { Text } from "./text.js";
+export { useForegroundTone } from "./use-foreground-tone.js";
+export { useNumberOfLines } from "./use-number-of-lines.js";
+export { useOverflowStrategy } from "./use-overflow-strategy.js";
+export { createTextStyles, useText } from "./use-text.js";
+export type { StrongProps } from "./strong.js";
+export type { TextProps } from "./text.js";
+export type { ForegroundTone } from "./use-foreground-tone.js";
+export type { TextOverflowStrategy } from "./use-overflow-strategy.js";

package/dist/declarations/src/strong.d.ts

@@ -0,0 +1,5 @@
+import type { ReactNode } from 'react';
+export type StrongProps = {
+    children: ReactNode;
+};
+export declare const Strong: ({ children }: StrongProps) => import("@emotion/react/jsx-runtime").JSX.Element;

package/dist/declarations/src/text.d.ts

@@ -0,0 +1,41 @@
+import type { CSSObject } from '@emotion/react';
+import type { BoxProps } from '@spark-web/box';
+import type { DataAttributeMap } from '@spark-web/utils/internal';
+import type { CSSProperties, ReactNode } from 'react';
+import type { TextOverflowStrategy } from "./use-overflow-strategy.js";
+import type { UseTextProps } from "./use-text.js";
+type InlineProps = {
+    align?: never;
+    /** Display as an inline element. */
+    inline?: boolean;
+    overflowStrategy?: never;
+};
+type BlockProps = {
+    /** The horizontal alignment. */
+    align?: 'left' | 'center' | 'right';
+    inline?: never;
+    /** Manage how text behaves with regard to overflow. */
+    overflowStrategy?: TextOverflowStrategy;
+};
+export type TextProps = Partial<UseTextProps> & {
+    /** The text content. */
+    children?: ReactNode;
+    /** Customizes the component element. */
+    css?: CSSObject;
+    /** Sets data attributes on the component. */
+    data?: DataAttributeMap;
+    /** An identifier which must be unique in the whole document. */
+    id?: BoxProps['id'];
+    /** When enabled, numbers will be the same width. Similar to a monospaced font. */
+    tabularNumbers?: boolean;
+    /** Transform the text casing. */
+    transform?: CSSProperties['textTransform'];
+    /** Truncate the text with an ellipsis after computing the text layout, including line wrapping,
+     * such that the total number of lines does not exceed this number. */
+    numberOfLines?: number;
+} & (InlineProps | BlockProps);
+export declare const Text: <Comp extends import("react").ElementType = "div">(props: {
+    as?: Comp | undefined;
+    ref?: import("react").Ref<Comp extends "symbol" | "svg" | "animate" | "animateMotion" | "animateTransform" | "circle" | "clipPath" | "defs" | "desc" | "ellipse" | "feBlend" | "feColorMatrix" | "feComponentTransfer" | "feComposite" | "feConvolveMatrix" | "feDiffuseLighting" | "feDisplacementMap" | "feDistantLight" | "feDropShadow" | "feFlood" | "feFuncA" | "feFuncB" | "feFuncG" | "feFuncR" | "feGaussianBlur" | "feImage" | "feMerge" | "feMergeNode" | "feMorphology" | "feOffset" | "fePointLight" | "feSpecularLighting" | "feSpotLight" | "feTile" | "feTurbulence" | "filter" | "foreignObject" | "g" | "image" | "line" | "linearGradient" | "marker" | "mask" | "metadata" | "mpath" | "path" | "pattern" | "polygon" | "polyline" | "radialGradient" | "rect" | "set" | "stop" | "switch" | "text" | "textPath" | "tspan" | "use" | "view" | keyof HTMLElementTagNameMap ? (HTMLElementTagNameMap & Pick<SVGElementTagNameMap, "symbol" | "svg" | "animate" | "animateMotion" | "animateTransform" | "circle" | "clipPath" | "defs" | "desc" | "ellipse" | "feBlend" | "feColorMatrix" | "feComponentTransfer" | "feComposite" | "feConvolveMatrix" | "feDiffuseLighting" | "feDisplacementMap" | "feDistantLight" | "feDropShadow" | "feFlood" | "feFuncA" | "feFuncB" | "feFuncG" | "feFuncR" | "feGaussianBlur" | "feImage" | "feMerge" | "feMergeNode" | "feMorphology" | "feOffset" | "fePointLight" | "feSpecularLighting" | "feSpotLight" | "feTile" | "feTurbulence" | "filter" | "foreignObject" | "g" | "image" | "line" | "linearGradient" | "marker" | "mask" | "metadata" | "mpath" | "path" | "pattern" | "polygon" | "polyline" | "radialGradient" | "rect" | "set" | "stop" | "switch" | "text" | "textPath" | "tspan" | "use" | "view">)[Comp] : Comp extends new (...args: any) => any ? InstanceType<Comp> : undefined> | undefined;
+} & (Omit<import("react").PropsWithoutRef<import("react").ComponentProps<Comp>>, "as"> & TextProps)) => import("react").ReactElement;
+export {};

package/dist/declarations/src/use-foreground-tone.d.ts

@@ -0,0 +1,3 @@
+import type { SparkTheme } from '@spark-web/theme';
+export type ForegroundTone = keyof Omit<SparkTheme['color']['foreground'], 'neutralInverted' | 'mutedInverted'>;
+export declare function useForegroundTone(tone: ForegroundTone): string;

package/dist/declarations/src/use-number-of-lines.d.ts

@@ -0,0 +1,2 @@
+import type { CSSProperties } from 'react';
+export declare const useNumberOfLines: (numberOfLines?: number) => CSSProperties;

package/dist/declarations/src/use-overflow-strategy.d.ts

@@ -0,0 +1,27 @@
+declare const strategyMap: {
+    readonly truncate: {
+        readonly display: "block";
+        readonly overflow: "hidden";
+        readonly textOverflow: "ellipsis";
+        readonly whiteSpace: "nowrap";
+    };
+    readonly nowrap: {
+        readonly whiteSpace: "nowrap";
+    };
+    readonly breakword: {
+        readonly display: "block";
+        readonly overflowWrap: "break-word";
+        readonly wordBreak: "break-word";
+        readonly wordWrap: "break-word";
+    };
+};
+export type TextOverflowStrategy = keyof typeof strategyMap;
+export declare function useOverflowStrategy(strategy?: TextOverflowStrategy): {
+    readonly whiteSpace: "nowrap";
+} | {
+    readonly display: "block";
+    readonly overflowWrap: "break-word";
+    readonly wordBreak: "break-word";
+    readonly wordWrap: "break-word";
+} | null;
+export {};

package/dist/declarations/src/use-text.d.ts

@@ -0,0 +1,31 @@
+import type { SparkTextDefinition, SparkTheme } from '@spark-web/theme';
+import type { ForegroundTone } from "./use-foreground-tone.js";
+export type UseTextProps = {
+    /** Apply leading-trim styles. */
+    baseline?: boolean;
+    /** The size of the text. */
+    size: keyof SparkTheme['typography']['text'];
+    /** The tone of the text. */
+    tone: ForegroundTone;
+    /** The weight of the text. */
+    weight?: keyof SparkTheme['typography']['fontWeight'];
+};
+export declare function useText({ baseline, size, tone, weight }: UseTextProps): (import("@emotion/serialize").CSSObject | undefined)[];
+export declare function createTextStyles({ fontSize, fontWeight, lineHeight, trims }: SparkTextDefinition, { includeTrims, includeWeight }?: {
+    includeTrims?: boolean | undefined;
+    includeWeight?: boolean | undefined;
+}): {
+    '::before'?: {
+        marginBottom: string;
+        content: string;
+        display: string;
+    } | undefined;
+    '::after'?: {
+        marginTop: string;
+        content: string;
+        display: string;
+    } | undefined;
+    fontSize: string;
+    fontWeight: number | undefined;
+    lineHeight: string;
+};

package/dist/spark-web-text.cjs.d.ts

@@ -0,0 +1,2 @@
+export * from "./declarations/src/index.js";
+//# sourceMappingURL=data:application/json;charset=utf-8;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic3Bhcmstd2ViLXRleHQuY2pzLmQudHMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuL2RlY2xhcmF0aW9ucy9zcmMvaW5kZXguZC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSJ9