@sesamehr/react-design-system 3.4.0 → 3.5.0

package/dist/Button/index.d.ts

@@ -1,7 +1,7 @@
 import { VariantProps } from 'class-variance-authority';
 export { Button, type ButtonProps } from './Button.tsx';
 export declare const buttonVariants: (props?: ({
-    variant?: "link" | "default" | "destructive" | "success" | "outline" | "secondary" | "ghost" | null | undefined;
+    variant?: "link" | "default" | "destructive" | "success" | "outline" | "secondary" | "ghost" | "ai" | null | undefined;
     size?: "icon" | "2xs" | "xs" | "sm" | "md" | "lg" | null | undefined;
 } & import('class-variance-authority/types').ClassProp) | undefined) => string;
 export type ButtonVariants = VariantProps<typeof buttonVariants>;

package/dist/Display/AiTag/AiTag.d.ts

@@ -0,0 +1,33 @@
+import { AiTagVariants } from './index.ts';
+/**
+ * `color` has to be omitted before it is redeclared: React's `HTMLAttributes`
+ * carries HTML's deprecated presentational `color` attribute as `string`, and
+ * the variant union will not widen to it.
+ */
+export interface AiTagProps extends Omit<React.HTMLAttributes<HTMLSpanElement>, 'color'> {
+    /**
+     * Whether this is the AI marker itself (`ai`, the two-hue gradient) or the
+     * quiet grey version for a surface that is already about AI.
+     */
+    color?: AiTagVariants['color'];
+    /** A line around nothing, or a filled surface. */
+    variant?: AiTagVariants['variant'];
+    /** 20px with 12px type, or 28px with 14px type. */
+    size?: AiTagVariants['size'];
+    dataTestid: string;
+}
+/**
+ * Says that what it sits next to came from Sesame AI.
+ *
+ * Built on `OxTag`'s shape rather than on a primitive, which is also what
+ * shadcn would have given: its `Badge` is a `<span>` with a variant map and no
+ * behaviour, because there is no behaviour here to get wrong. The AI marker is
+ * not interactive, takes no click and is not a tab stop — if pressing it should
+ * do something, that is an `OxChip`.
+ *
+ * The glyph goes in `children` carrying `data-slot="icon"`, the way `OxTag`
+ * takes one, and is not shipped inside with a prop to hide it. Figma spells the
+ * same axis as a `Show icon` boolean, and writing the icon or not writing it is
+ * the one spelling of that axis which needs no prop and cannot be got wrong.
+ */
+export declare const AiTag: import('react').ForwardRefExoticComponent<AiTagProps & import('react').RefAttributes<HTMLSpanElement>>;

package/dist/Display/AiTag/index.d.ts

@@ -0,0 +1,21 @@
+import { VariantProps } from 'class-variance-authority';
+export { AiTag, type AiTagProps } from './AiTag.tsx';
+/**
+ * The marker that says a piece of content came from Sesame AI.
+ *
+ * Two axes, and they are not the same axis twice. `color` is *whether this is
+ * the AI marker at all*: `ai` paints the two-hue gradient nothing else in the
+ * system uses, `muted` is the same pill in grey for when the surrounding UI is
+ * already about AI and a second gradient would only shout. `variant` is how
+ * loudly either one is painted — a line around nothing, or a filled surface.
+ *
+ * The design calls the second axis `Style`; it is `variant` here because a prop
+ * named `style` would eat the caller's inline styles. `OxTag` renamed it for
+ * the same reason.
+ */
+export declare const aiTagVariants: (props?: ({
+    color?: "ai" | "muted" | null | undefined;
+    variant?: "filled" | "outline" | null | undefined;
+    size?: "sm" | "md" | null | undefined;
+} & import('class-variance-authority/types').ClassProp) | undefined) => string;
+export type AiTagVariants = VariantProps<typeof aiTagVariants>;

package/dist/Display/Avatar/index.d.ts

@@ -23,12 +23,12 @@ export { useAvatarBullet } from './hooks/useAvatarBullet.ts';
  */
 export declare const avatarSquareVariants: (props?: ({
     size?: "xs" | "sm" | "md" | "lg" | "xl" | null | undefined;
-    tone?: "neutral" | "brand" | null | undefined;
+    tone?: "brand" | "neutral" | null | undefined;
     disabled?: boolean | null | undefined;
 } & import('class-variance-authority/types').ClassProp) | undefined) => string;
 export declare const avatarRoundedVariants: (props?: ({
     size?: "xs" | "sm" | "md" | "lg" | "xl" | null | undefined;
-    tone?: "neutral" | "brand" | null | undefined;
+    tone?: "brand" | "neutral" | null | undefined;
     disabled?: boolean | null | undefined;
 } & import('class-variance-authority/types').ClassProp) | undefined) => string;
 export type AvatarSquareVariants = VariantProps<typeof avatarSquareVariants>;

package/dist/Display/Badge/index.d.ts

@@ -12,6 +12,6 @@ export { Badge, type BadgeProps } from './Badge.tsx';
  */
 export declare const badgeVariants: (props?: ({
     size?: "sm" | "md" | "lg" | null | undefined;
-    color?: "error" | "neutral" | "brand" | null | undefined;
+    color?: "brand" | "error" | "neutral" | null | undefined;
 } & import('class-variance-authority/types').ClassProp) | undefined) => string;
 export type BadgeVariants = VariantProps<typeof badgeVariants>;

package/dist/Display/BrandLogo/BrandLogo.d.ts

@@ -0,0 +1,53 @@
+import { BrandLogoVariants } from './index.ts';
+/**
+ * `color` has to be omitted before it is redeclared: React's `SVGAttributes`
+ * carries SVG's presentational `color` attribute as `string`, and the variant
+ * union will not widen to it.
+ */
+export interface BrandLogoProps extends Omit<React.SVGAttributes<SVGSVGElement>, 'color' | 'type'> {
+    /**
+     * The symbol with the wordmark beside it, or the symbol on its own — which
+     * is what a collapsed sidebar and a favicon-sized slot want.
+     */
+    type?: BrandLogoVariants['type'];
+    /**
+     * The ink: `dark` for a light background, `light` for a dark one. Not a
+     * dark-mode switch — see the note below.
+     */
+    color?: BrandLogoVariants['color'];
+    /** 32px tall, or 88px. The width follows the art. */
+    size?: BrandLogoVariants['size'];
+    dataTestid: string;
+}
+/**
+ * The Sesame logo.
+ *
+ * **It uses primitive colours on purpose, and this is the note that stops
+ * someone "fixing" it.** `dark` is `brand-500` and `light` is `white`, read
+ * straight off the primitive ramp rather than through `--brand` or
+ * `--foreground`. A semantic token is a promise that the value may be
+ * re-pointed — by a theme, by dark mode, by a consumer overriding
+ * `--ox-color-brand-500`'s semantic layer — and a logo is the one thing in the
+ * system that must not move when any of that happens. It is the brand, not a
+ * surface painted in brand colours. `@sesame/orxata-icons` is the only other
+ * sanctioned exception, for the same reason.
+ *
+ * So: the two colours here are *not* a dark-mode pair. `color` says what the
+ * logo is sitting on, not what the theme is — `light` is the white logo for a
+ * navy header, and it stays white in light mode.
+ *
+ * No primitive underneath, and nothing to borrow: shadcn has no logo and
+ * neither does Radix. There is no state, no keyboard and no coordination, so
+ * there is nothing for a headless primitive to hold — it is one `<svg>`.
+ *
+ * `role="img"` with no name by default, which is deliberate. A logo in a
+ * sidebar header beside the word "Sesame" is decoration and naming it twice is
+ * noise; a logo that *is* the link home needs the name on the link, not on the
+ * art. Where it is genuinely the only thing identifying the page, `children`
+ * becomes an SVG `<title>`:
+ *
+ * ```tsx
+ * <OxBrandLogo dataTestid="logo">{t('brand.name')}</OxBrandLogo>
+ * ```
+ */
+export declare const BrandLogo: import('react').ForwardRefExoticComponent<BrandLogoProps & import('react').RefAttributes<SVGSVGElement>>;

package/dist/Display/BrandLogo/brandLogoArt.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The Sesame logo, as the v3 board draws it.
+ *
+ * Path data rather than an asset file, and it lives beside the component rather
+ * than in `@sesame/orxata-icons`, for two reasons. The icons package renders an
+ * asset as `innerHTML` of an `<i>` and its one Sesame brand file is still the
+ * v2 mark — green accent, navy hexagon — so using it would ship the old logo;
+ * and adding v3 art there would tie this component to an icons release. Here it
+ * is versioned with the component that draws it.
+ *
+ * Every path is `fill="currentColor"` at render time. The board paints all of
+ * them with one colour per variant, so one `color` is all the markup needs —
+ * see the component for why that is worth saying out loud.
+ *
+ * Composed from the vector groups Figma exports, each placed with the offset
+ * the group has inside its variant frame. Regenerated rather than edited: the
+ * numbers are measurements, and a hand-nudged logo is a wrong logo.
+ */
+export interface BrandLogoArt {
+    viewBox: string;
+    groups: {
+        transform: string;
+        paths: string[];
+    }[];
+}
+/** Symbol plus the "sesame" wordmark: 113.6 x 32, which is 3.55:1. */
+export declare const BRAND_LOGO_FULL: BrandLogoArt;
+/** The symbol on its own, square. */
+export declare const BRAND_LOGO_MARK: BrandLogoArt;

package/dist/Display/BrandLogo/index.d.ts

@@ -0,0 +1,17 @@
+import { VariantProps } from 'class-variance-authority';
+export { BrandLogo, type BrandLogoProps } from './BrandLogo.tsx';
+export { type BrandLogoArt } from './brandLogoArt.ts';
+/**
+ * The Sesame logo.
+ *
+ * `type` picks the art and `color` picks the ink. There is no `variant` axis,
+ * which is where this differs from every other component in the package — see
+ * the note in `BrandLogo.tsx` about the board's `Style` axis, which draws the
+ * same two colours either way.
+ */
+export declare const brandLogoVariants: (props?: ({
+    type?: "mark" | "full" | null | undefined;
+    color?: "dark" | "light" | null | undefined;
+    size?: "md" | "lg" | null | undefined;
+} & import('class-variance-authority/types').ClassProp) | undefined) => string;
+export type BrandLogoVariants = VariantProps<typeof brandLogoVariants>;

package/dist/Display/FileCard/FileCard.d.ts

@@ -1,30 +1,72 @@
+import { FileCardVariants } from './index.ts';
 /**
- * One attached file as a row. Mirrors `@sesame/orxata-core` FileCard.
+ * One attached file as a row: a type badge, the file's name, a second line of
+ * detail, somewhere for the caller to put what you can do to it, and an
+ * optional bar across the bottom while it moves.
  *
- * Built on `Card` rather than redrawing the shell. The radius, the border and
- * the white surface are already a component, and the only reason this file has
- * a stylesheet at all is the row inside it. `flat` is the card the design
- * draws: border, no lift — `Card`'s `flat` keeps the outline and drops only the
- * shadow and the glass.
+ * Mirrors `@sesame/orxata-core` FileCard.
  *
- * ### Why `name` and `meta` are props and the other two are nodes
+ * ### Figma draws this on two pages and they are one component
  *
- * Sameness is the product for the text, exactly as in `AvatarDetails`: every
- * file row we ship is two lines at the same sizes and weights, and a node is
- * where that guarantee goes to die — the first caller to put a link, a badge or
- * a third line in it ends the point of having the component. `meta` is
- * deliberately not called `size`: what the second line says is the
- * application's business ("1,56 MB", "PDF · yesterday", "Uploaded by Ana"), and
- * naming it after one of those would be a lie the day someone passes another.
+ * `File card` is the file you already have — display and download. `File item`
+ * is the row inside `File upload` while it arrives, with `State = Loading |
+ * Uploaded | Hover | Error`. They are the same row: the same `_File / Type`
+ * badge, the same name over the same meta line, the same box. What differs is
+ * which control sits on the right — a download in one, a retry or a remove in
+ * the other — and that is already a slot.
  *
- * The glyph and the action are the opposite case. Mapping an extension to an
- * icon is application knowledge — there are hundreds of extensions and we know
- * none of them — so `icon` takes a node and falls back to a generic file glyph,
- * which is the one honest thing a design system can draw. And `action` takes a
- * node because *which* action is not ours either: download, delete, share,
- * retry, or nothing at all. It also settles the accessible name, which we
- * cannot supply since the design system ships no strings — whatever the caller
- * puts there brings its own, and `IconButton` refuses to render without one.
+ * So there is no `OxFileItem` and there is not going to be one. The test for
+ * splitting a component here is logic, state or context interaction, and the
+ * upload side has none of the three: the progress is a number that becomes a
+ * width, the error is a class, and everything else that changes is slot
+ * content. A second component would wrap this one, add classes and forward a
+ * slot, which is the shape the architecture rules name as premature
+ * abstraction.
+ *
+ * ### The text is slots, which is a reversal
+ *
+ * The name and the second line used to be **strings** here, argued for on the
+ * grounds that sameness is the product and a node is where that guarantee
+ * dies. It was the wrong trade. Content in props is the pattern
+ * composition-over-configuration exists to stop, and the guarantee it was
+ * buying is held by the stylesheet anyway — the two lines are sized and
+ * coloured here whatever goes in them. Keeping them as strings also spent two
+ * of five on content at the exact moment the board needed three for `type`,
+ * `surface` and `state`.
+ *
+ * `children` is the name; `meta` is the second line, and it is called that
+ * rather than `size` because what belongs there is the application's business —
+ * `PDF · 230 KB` on the board, but `Uploading… 60 %` on the upload one and
+ * `Uploaded by Ana` in a list.
+ *
+ * ### `type` is the colour; the badge's content is still yours
+ *
+ * Mapping a file to a glyph is application knowledge — there are hundreds of
+ * extensions and the set is open — which is why the badge has a slot. The
+ * board closes the *colour* at five named types and binds a token to each,
+ * which is a design decision and therefore ours. Which of the five `.odt`,
+ * `.numbers` or `.pages` belongs to is not.
+ *
+ * So the two split cleanly: `type` picks the ramp, `icon` carries what is
+ * printed on it. The board prints a three-letter abbreviation — `PDF`, `DOC`,
+ * `XLS`, `PPT` — and those come from the caller, because this package ships no
+ * strings and because the generic badge has no abbreviation to ship (Figma
+ * draws `ZIP` there, which is an example of a generic file and not the name of
+ * one). Pass nothing and the badge keeps the ramp and falls back to a plain
+ * file glyph, which is the one honest default. A sixth file type nobody has
+ * asked us for is `--ox-file-card-glyph-background` on the root.
+ *
+ * ### The bar is drawn here rather than being an `OxProgress`
+ *
+ * `OxProgress` is an 8px pill with a rounded fill on a `secondary` track. This
+ * is a 3px hairline flush against the bottom edge, square, and on `brand` it
+ * swaps both of its colours for `chat-user-media` and `brand-foreground`.
+ * Reaching for the component would mean overriding every declaration it has
+ * from outside, where the two module classes weigh the same — so which
+ * stylesheet the bundler emitted first would decide what the bar looked like.
+ * Two elements and `role="progressbar"` cost less and cannot lose that race.
+ * The bar names itself after the file, via the id on the name, so a screen
+ * reader says the file and not just a percentage.
  *
  * ### What it deliberately does not do
  *
@@ -32,33 +74,52 @@
  * `width`, and that figure belongs to the screen it was drawn on, not to the
  * component: a card that hardcodes its own width cannot sit in a grid, a
  * sidebar or a flexible column, and the parent owns external layout. It fills
- * what it is given. The 72px height stays, because that one is internal — a
- * list of these has to have rows of equal height, and long names truncate
- * rather than growing the row.
+ * what it is given. The height stays, because that one is internal — a list of
+ * these has to have rows of equal height, and long names truncate rather than
+ * grow the row.
  *
- * **The root is not a button.** It already contains an interactive control, and
- * a button inside a button is invalid HTML; making the root activate would also
- * mean inventing a focus and keyboard contract the design has nothing to say
- * about. A caller who wants the whole row to do something wraps it, or puts a
- * link in `action`.
+ * **The root is not a button.** It already contains an interactive control,
+ * and a button inside a button is invalid HTML; making the root activate would
+ * also mean inventing a focus and keyboard contract the design has nothing to
+ * say about. A caller who wants the whole row to do something wraps it, or
+ * puts a link in `action`. The hover tint the upload board draws is on the row
+ * all the same, because the row is what the pointer is over whichever of those
+ * two the caller chose.
  */
-export interface FileCardProps extends Omit<React.ComponentPropsWithoutRef<'div'>, 'title'> {
-    /** The file's name. Truncates rather than wrapping — the row is a fixed height. */
-    name: string;
+export interface FileCardProps extends React.ComponentPropsWithoutRef<'div'> {
+    /**
+     * Which of the five colour ramps the badge wears. Not which extension the
+     * file has — that mapping is yours, and the badge's content is a slot.
+     */
+    type?: FileCardVariants['type'];
+    /**
+     * Which side of a chat bubble this sits in: `brand` inside the reader's own
+     * message, `default` anywhere else. The same axis the attachments carry.
+     */
+    surface?: FileCardVariants['surface'];
+    /**
+     * `error` repaints the border and the meta line. Loading and uploaded are
+     * not states here — they are what you put in `meta` and `action`.
+     */
+    state?: FileCardVariants['state'];
+    /**
+     * How far along, 0 to 100. Present at all means the bar is drawn; omit it
+     * and there is no bar and no `progressbar` role.
+     */
+    progress?: number;
     /**
-     * The second line: whatever the app knows about the file. Size in the
-     * design, but a type, a date or an author read just as well. Omit it and the
-     * row is one line.
+     * The second line: a type and a size, a progress reading, or the reason an
+     * upload failed. Omit it and the row is one line.
      */
-    meta?: string;
+    meta?: React.ReactNode;
     /**
-     * The glyph in the ring. Defaults to a generic file — mapping an extension to
-     * an icon is the application's knowledge, not ours.
+     * What is printed on the badge — the board uses a three-letter
+     * abbreviation. Left empty it falls back to a generic file glyph.
      */
     icon?: React.ReactNode;
     /**
-     * The one thing you can do to this file. Nothing by default; whatever you put
-     * here brings its own accessible name.
+     * What you can do to this file. Whatever you put here brings its own
+     * accessible name.
      */
     action?: React.ReactNode;
     dataTestid: string;

package/dist/Display/FileCard/index.d.ts

@@ -1 +1,32 @@
+import { VariantProps } from 'class-variance-authority';
 export { FileCard, type FileCardProps } from './FileCard.tsx';
+/**
+ * Three axes, and each of them is a thing the component draws rather than a
+ * thing the caller writes.
+ *
+ * `type` is the colour of the badge, not the text in it. The v3 board closes
+ * the set at five — PDF, Word, Excel, PowerPoint and a generic — and pins a
+ * colour to each (`file-pdf`, `file-word`, `file-excel`, `file-powerpoint`,
+ * `file-generic`). Which of the five a `.numbers` or an `.odt` belongs to is
+ * still the application's call; see the note in `FileCard.tsx`.
+ *
+ * `surface` is Figma's axis of the same name, with the same two values every
+ * chat attachment carries. The Vue original types it as the attachments'
+ * shared `AttachmentSurface`; this package has no `internal/AttachmentMedia`
+ * yet, so the prop reads the union off this cva instead — the same two values,
+ * to be re-pointed when the attachments port lands.
+ *
+ * `state` is two values where Figma's `File item` board draws four, and the
+ * other two are not missing — they are somewhere else. `Loading` and
+ * `Uploaded` differ only in what sits in the `action` slot and what the `meta`
+ * slot says, both of which are the caller's content; `Hover` is a tint, which
+ * is `:hover`. `Error` is the one state that is neither: it repaints the
+ * card's own border and its own meta line, and nothing a caller passes in
+ * could reach either.
+ */
+export declare const fileCardVariants: (props?: ({
+    type?: "pdf" | "word" | "excel" | "powerpoint" | "file" | null | undefined;
+    surface?: "default" | "brand" | null | undefined;
+    state?: "default" | "error" | null | undefined;
+} & import('class-variance-authority/types').ClassProp) | undefined) => string;
+export type FileCardVariants = VariantProps<typeof fileCardVariants>;

package/dist/Display/ImageAttachment/ImageAttachment.d.ts

@@ -0,0 +1,58 @@
+import { AttachmentImage, AttachmentSurface } from '../../internal/AttachmentMedia/index.ts';
+/**
+ * The pictures attached to a chat message: one across the bubble, or a 2×2
+ * grid with a count on the last cell.
+ * Mirrors `@sesame/orxata-core` ImageAttachment.
+ *
+ * No primitive underneath. shadcn has nothing in this shape and neither does
+ * Radix — a grid of image buttons has no roving focus, no selection and no
+ * open state to coordinate, so there is nothing for a headless primitive to
+ * hold. Each cell is a plain `<button>` in document order, which is what Radix
+ * would have rendered anyway.
+ *
+ * ### `Type` is not a prop, because the content already decides it
+ *
+ * Figma's axis holds `Image` and `Gallery`, and its own usage board says when
+ * each applies: one picture is `Image`, two or more is `Gallery`, and from the
+ * fifth the last cell carries `+N`. All three are counts, so `images.length`
+ * answers them and a prop would only let a caller contradict it. `More count`
+ * goes the same way: it is `images.length - 4`, so pass every picture you have
+ * and at most four are ever rendered.
+ *
+ * ### Each cell is a button
+ *
+ * The behaviour board puts the viewer behind a click and asks for keyboard
+ * access, and unlike `FileCard` — whose root refuses to be a control because it
+ * *contains* one — there is nothing interactive in here to nest. A gallery's
+ * cells could not be wrapped from outside either: the component renders them.
+ * So `onOpen` carries the index, and `images[index]` is the picture to show.
+ *
+ * ### The `+N` cell is still its own picture
+ *
+ * It is the fourth image under a scrim, not a separate control, so its
+ * accessible name is that image's `alt` and the count is `aria-hidden`
+ * decoration on top. The accessibility board asks instead for an aria-label
+ * reading "see N more images" — which this package cannot supply, because it
+ * ships no strings of its own and has no catalogue to add one to. Opening the
+ * viewer at the fourth picture reaches the rest from there.
+ */
+export interface ImageAttachmentProps extends React.ComponentPropsWithoutRef<'div'> {
+    /**
+     * Every picture attached, in order. One renders across the bubble; two or
+     * more render as a grid of up to four, and the rest become the `+N`.
+     */
+    images: AttachmentImage[];
+    /**
+     * Which side of the bubble this sits in: `brand` inside the reader's own
+     * message, `default` inside anyone else's.
+     */
+    surface?: AttachmentSurface;
+    /**
+     * A picture was activated. The index is into `images`, so the last cell of a
+     * clipped gallery still reports `3` and the viewer reaches the rest from
+     * there. Ports the Vue `@open` emit.
+     */
+    onOpen?: (index: number) => void;
+    dataTestid: string;
+}
+export declare const ImageAttachment: import('react').ForwardRefExoticComponent<ImageAttachmentProps & import('react').RefAttributes<HTMLDivElement>>;

package/dist/Display/ImageAttachment/index.d.ts

@@ -0,0 +1,2 @@
+export { ImageAttachment, type ImageAttachmentProps, } from './ImageAttachment.tsx';
+export type { AttachmentImage, AttachmentSurface, } from '../../internal/AttachmentMedia/index.ts';

package/dist/Display/LinkPreview/LinkPreview.d.ts

@@ -0,0 +1,65 @@
+import { ReactNode } from 'react';
+import { AttachmentImage, AttachmentSurface } from '../../internal/AttachmentMedia/index.ts';
+/**
+ * A URL shared in a chat, unfurled: the page's image, its domain, its title and
+ * an extract.
+ * Mirrors `@sesame/orxata-core` LinkPreview.
+ *
+ * No primitive underneath. shadcn has no link card and Radix has none either —
+ * the whole thing is one `<a>`, which is what Radix's `Primitive` would have
+ * rendered, and there is no state, no keyboard contract and no composition for
+ * a headless primitive to hold. The image, its tint and the `Surface` axis come
+ * from `AttachmentMedia`, shared with the other four attachments.
+ *
+ * ### The card is one link, named by its title
+ *
+ * The accessibility board asks for exactly that, and the domain and the extract
+ * are inside the `<a>` too — so `aria-labelledby` points the link's name at the
+ * title and leaves the other two as text a reader still reaches. Without it the
+ * name would be all three lines read out as one sentence.
+ *
+ * `children` is therefore the title, and it is the one piece of content this
+ * component cannot do without: an empty one leaves the link with no accessible
+ * name at all.
+ *
+ * The board also asks the card to announce that it opens in a new tab. The
+ * `target` and the `rel` are here; the wording is not, because this package
+ * ships no strings and has no catalogue to add one to.
+ *
+ * ### Three nodes and not three strings
+ *
+ * `title` and `description` are names the composition rule does not allow as
+ * props, and a domain beside them as a plain string prop would be the same
+ * component taking its text two different ways. So all three are `ReactNode` —
+ * which is also what lets a caller put a `<time>`, a mark or an abbreviation in
+ * one, and what makes the sibling attachments consistent:
+ * `OxVideoAttachment`'s duration is a node for the same reason.
+ *
+ * ### Without an image the header is simply gone
+ *
+ * The usage board's rule, and it needs no flag: `image` is optional and the
+ * media is conditional on it, which leaves the text block alone in the card
+ * rather than an empty grey band above it. That is the one place this differs
+ * from `OxVideoAttachment`, where the tint *is* the placeholder.
+ */
+export interface LinkPreviewProps extends React.ComponentPropsWithoutRef<'a'> {
+    /** Where the link goes. Opened in a new tab, as the behaviour board asks. */
+    href: string;
+    /**
+     * The page's image. Omitted — or absent from the page — leaves the card as
+     * its text block, which is the usage board's "no image" pattern. The boards
+     * call it decoration, so pass `alt: ''` unless it carries meaning of its own.
+     */
+    image?: AttachmentImage;
+    /**
+     * Which side of the bubble this sits in: `brand` inside the reader's own
+     * message, `default` inside anyone else's.
+     */
+    surface?: AttachmentSurface;
+    /** The domain of the shared URL, beside a globe glyph. Ports `#domain`. */
+    domain?: ReactNode;
+    /** An extract from the page. Two lines, then an ellipsis. Ports `#description`. */
+    description?: ReactNode;
+    dataTestid: string;
+}
+export declare const LinkPreview: import('react').ForwardRefExoticComponent<LinkPreviewProps & import('react').RefAttributes<HTMLAnchorElement>>;

package/dist/Display/LinkPreview/index.d.ts

@@ -0,0 +1 @@
+export { LinkPreview, type LinkPreviewProps } from './LinkPreview.tsx';

package/dist/Display/LocationAttachment/LocationAttachment.d.ts

@@ -0,0 +1,71 @@
+import { ReactNode } from 'react';
+import { AttachmentImage, AttachmentSurface } from '../../internal/AttachmentMedia/index.ts';
+/**
+ * A place shared in a chat: a map band, the place's name and its address.
+ * Mirrors `@sesame/orxata-core` LocationAttachment.
+ *
+ * No primitive underneath, and here there was never a candidate — shadcn has
+ * no map card, Radix has no map anything, and the whole component is one `<a>`
+ * with no state, no keyboard contract beyond a link's own and nothing to
+ * coordinate. `AttachmentMedia` supplies the band, its tint and the `Surface`
+ * axis, shared with the other four attachments.
+ *
+ * ### The map is a prop, and the pin is what shows without one
+ *
+ * A prop rather than a node, on two counts. `OxImageAttachment`,
+ * `OxVideoAttachment` and `OxLinkPreview` all take their picture as an
+ * `image?: AttachmentImage`, and a node here would make one of the four odd for
+ * no gain a caller could use. And what the board draws in the band is a static
+ * map render — a URL, the same kind of thing as the `href` beside it, not
+ * arbitrary markup.
+ *
+ * The image **replaces** the pin rather than sitting under it, because the
+ * board's anatomy calls part one "map (placeholder)" with the pin inside it:
+ * the pin is what stands in for a map that is not there. So it is
+ * `AttachmentMedia`'s `placeholder`, which is also what makes it the
+ * failed-to-load state for free.
+ *
+ * Without an image the band is decoration: `AttachmentMedia` marks a
+ * placeholder it cannot name `aria-hidden`, which is the accessibility board's
+ * "the map is decorative". With one, the `alt` decides — and `''` is the right
+ * answer for a map of an address the line below already spells out.
+ *
+ * ### One link, named by what is in it
+ *
+ * Activating it opens the device's map application, which is an `href` — a
+ * `geo:` URI or a maps URL, the application's choice. The place and the address
+ * both sit inside the `<a>`, so the link's accessible name is the two of them,
+ * which is what the accessibility board asks for bar its "Location:" prefix.
+ * That prefix is a string, and this package ships none.
+ *
+ * Unlike `OxLinkPreview` there is no `aria-labelledby` here: that one has three
+ * lines and a board saying the name is the title alone, while this one has two
+ * and a board saying the name is both.
+ *
+ * ### Place and address are nodes
+ *
+ * The same reason as the siblings: `OxLinkPreview` carries a title and a
+ * description, names the composition rule does not allow as props, so the
+ * family takes its text as nodes rather than two different ways.
+ */
+export interface LocationAttachmentProps extends React.ComponentPropsWithoutRef<'a'> {
+    /**
+     * Where the card goes — a `geo:` URI or a maps URL. Which one, and whether it
+     * carries coordinates or a query, is the application's knowledge.
+     */
+    href: string;
+    /**
+     * The static map of the place. It replaces the pin, which is the placeholder
+     * it stands in for; omitted — or failed to load — leaves the pin on the tint.
+     */
+    image?: AttachmentImage;
+    /**
+     * Which side of the bubble this sits in: `brand` inside the reader's own
+     * message, `default` inside anyone else's.
+     */
+    surface?: AttachmentSurface;
+    /** The full address. One line, then an ellipsis. Ports the `#address` slot. */
+    address?: ReactNode;
+    dataTestid: string;
+}
+export declare const LocationAttachment: import('react').ForwardRefExoticComponent<LocationAttachmentProps & import('react').RefAttributes<HTMLAnchorElement>>;

package/dist/Display/LocationAttachment/index.d.ts

@@ -0,0 +1 @@
+export { LocationAttachment, type LocationAttachmentProps, } from './LocationAttachment.tsx';