@q1travel/design-system 0.21.0 → 0.22.0

package/contracts/design.dark.md

@@ -430,6 +430,8 @@ These components ship in the package. Compose from this list before writing new
 
 `q1-design ls` prints this list from the installed package, and `q1-design doc <name>` prints one component's public API. Use those when the package is installed; use this section when it is not.
 
+**Record activity.** Timeline, TimelineItem, Marker, Message, Mention, Composer, Attachment. Timeline uses chronological ol/li with tone dots or Avatar; Marker keeps system events quiet and dates centered. Message supports pending/failed and caller actions; Mention renders caller-owned inline member references using action-text and the selected surface. Composer is a textarea combobox with listbox mentions, Enter sends and Shift+Enter inserts a newline; IME composition never sends or picks. Attachment reuses Progress and named removal. Network, permissions and notifications remain caller-owned.
+
 **Actions.** Button, ButtonLink, IconButton, SplitButton, LoadMoreButton, ClearButton, CopyButton, FilterChip, Link, Toolbar.
 
 - Button carries the action. ButtonLink navigates but reads as a button, for a page-level call to action. Link reads as text, inside a sentence. Substituting one for another makes the page read wrong.

package/contracts/design.md

@@ -430,6 +430,8 @@ These components ship in the package. Compose from this list before writing new
 
 `q1-design ls` prints this list from the installed package, and `q1-design doc <name>` prints one component's public API. Use those when the package is installed; use this section when it is not.
 
+**Record activity.** Timeline, TimelineItem, Marker, Message, Mention, Composer, Attachment. Timeline uses chronological ol/li with tone dots or Avatar; Marker keeps system events quiet and dates centered. Message supports pending/failed and caller actions; Mention renders caller-owned inline member references using action-text and the selected surface. Composer is a textarea combobox with listbox mentions, Enter sends and Shift+Enter inserts a newline; IME composition never sends or picks. Attachment reuses Progress and named removal. Network, permissions and notifications remain caller-owned.
+
 **Actions.** Button, ButtonLink, IconButton, SplitButton, LoadMoreButton, ClearButton, CopyButton, FilterChip, Link, Toolbar.
 
 - Button carries the action. ButtonLink navigates but reads as a button, for a page-level call to action. Link reads as text, inside a sentence. Substituting one for another makes the page read wrong.

package/contracts/implementation-map.md

@@ -9,6 +9,7 @@ README owns the repository inventory and generated-file boundary. This file owns
 | Reference intent | q1travel semantic | Canonical surface | Token source | State | Responsive | Accessibility |
 | --- | --- | --- | --- | --- | --- | --- |
 | Bounded documentation frame | Public design-system shell | `AppShell`, `Sidebar`, `Topbar` | `--q1-color-bg-canvas`, `--q1-color-border`, spacing tokens | Route changes reset document scroll | Frame width and sidebar collapse through layout CSS | Landmarks, keyboard search, focus-visible ring |
+| Aligned date-range field | Date-range trigger shares the FieldSize scale | `Calendar`, `RangeField` (`fieldSize`; `size` remains grid-only) | `--q1-control-height-default`, `--q1-space-6`, `--q1-space-8`, `--q1-space-2`, `--q1-touch-target-min` | Draft, apply, clear and popover keyboard behavior preserved; clear/caret centered | Default md40 matches Select/Input; coarse44 matches Select | Named sibling buttons, APG date-picker dialog and focus return |
 | Compact dashboard filters | Consumer-owned filter picker | `FilterChip` | `--q1-space-7` (28px), border-strong, text-secondary, action-text, shared focus | Unset dashed CirclePlus; set solid leading CircleX clear, label, divider, value and ChevronDown | Ellipsis bounds long values; shared TouchTarget preserves coarse 44px targets | Sibling native buttons, clear before picker in Tab order, focus returns to picker |
 | Compact search and command menu | Fast documentation navigation | `CommandMenu`, `Topbar` search trigger | Surface, border, text, focus tokens | Open, active option, escape close | Dialog width clamps on small screens | `role="dialog"`, `aria-modal`, keyboard navigation |
 | Foundation page rhythm | Scannable reference pages | `PageHeader`, `SpecSection`, `SpecTable` | Heading, copy, border, spacing tokens | None beyond links and focus | Tables scroll horizontally when needed | Semantic headings and tables |
@@ -90,3 +91,7 @@ Click, ArrowLeft/ArrowRight, Home, and End notify activation; controlled selecti
 changes only when the parent updates `value`. Keyboard navigation follows the
 focused enabled tab while the parent update is pending, and a later value update
 does not pull focus from the activated button. Consumers own URL synchronization.
+
+## Record activity (owner approved 2026-10-06)
+
+Timeline / TimelineItem (ol/li, 8px token dot or Avatar), Marker (quiet actor/time, date separator), Message (default/pending/failed, caller actions) / Mention (inline action-text on selected surface), Composer (Tier A textarea combobox/listbox, IME guard, Enter send / Shift+Enter newline), Attachment (Progress, retry/remove) are public package components. `/patterns/record-activity` composes order facts, Switch, chronological activity and a pinned Composer. Existing tokens only; data, permissions, network and notifications remain caller-owned.

package/dist-pkg/design-system.d.ts

@@ -23,6 +23,18 @@ import { TextareaHTMLAttributes } from 'react';
 
 export declare function addDays(date: Date, amount: number): Date;
 
+export declare function Attachment({ name, size, type, progress, error, onRetry, onRemove, }: AttachmentProps): JSX.Element;
+
+export declare type AttachmentProps = {
+    name: string;
+    size?: ReactNode;
+    type?: 'file' | 'image';
+    progress?: number;
+    error?: ReactNode;
+    onRetry?: () => void;
+    onRemove?: () => void;
+};
+
 export declare function AuthCard({ title, description, action, className }: AuthCardProps): JSX.Element;
 
 /** Focused presentational card for account entry and connection flows. */
@@ -584,6 +596,27 @@ export declare type CommandMenuSection = {
     items: CommandMenuItem[];
 };
 
+export declare function Composer({ onSubmit, onAttach, attachments, mentions, disabled, }: ComposerProps): JSX.Element;
+
+export declare type ComposerMention = {
+    id: string;
+    label: string;
+    description?: string;
+};
+
+export declare type ComposerProps = {
+    onSubmit: (submission: ComposerSubmission) => void;
+    onAttach?: () => void;
+    attachments?: ReactNode;
+    mentions?: ComposerMention[];
+    disabled?: boolean;
+};
+
+export declare type ComposerSubmission = {
+    text: string;
+    mentionIds: string[];
+};
+
 export declare function ContextCard({ name, identity, rows, action, onAction, actionHref, placement, align, children, }: ContextCardProps): JSX.Element;
 
 declare type ContextCardAction = {
@@ -1155,6 +1188,21 @@ declare type LoadMoreButtonOwnProps = {
 
 export declare type LoadMoreButtonProps = LoadMoreButtonOwnProps & Omit<ComponentPropsWithoutRef<'button'>, keyof LoadMoreButtonOwnProps>;
 
+export declare function Marker({ actor, time, variant, children, }: MarkerProps): JSX.Element;
+
+export declare type MarkerProps = {
+    actor?: ReactNode;
+    time?: ReactNode;
+    variant?: 'default' | 'separator';
+    children: ReactNode;
+};
+
+export declare function Mention({ children }: MentionProps): JSX.Element;
+
+export declare type MentionProps = {
+    children: ReactNode;
+};
+
 export declare function Menu({ label, entries, withChevron, align, triggerContent }: {
     label: string;
     entries: MenuEntry[];
@@ -1217,6 +1265,19 @@ declare type MenuLinkBase = {
     suffix?: ReactNode;
 };
 
+export declare function Message({ author, avatar, time, children, attachments, actions, status, onRetry, }: MessageProps): JSX.Element;
+
+export declare type MessageProps = {
+    author: ReactNode;
+    avatar?: ReactNode;
+    time?: ReactNode;
+    children: ReactNode;
+    attachments?: ReactNode;
+    actions?: ReactNode;
+    status?: 'default' | 'pending' | 'failed';
+    onRetry?: () => void;
+};
+
 export declare function MiddleTruncate({ text, tailLength, mono }: {
     text: string;
     tailLength?: number;
@@ -1516,10 +1577,12 @@ export declare function Radio({ ...props }: RadioProps): JSX.Element;
 /** Radio 的完整 props。 */
 export declare type RadioProps = ControlOptionOwnProps & (FieldShellProps | FieldBareProps) & ControlOptionNativeInputProps;
 
-export declare function RangeField({ layout, trigger, size, minValue, maxValue, pinnedTimezone, today, value, onChange, }: {
+export declare function RangeField({ layout, trigger, size, fieldSize, minValue, maxValue, pinnedTimezone, today, value, onChange, }: {
     layout?: PopoverLayout;
     trigger?: TriggerKind;
     size?: CalendarSize;
+    /** 仅控制触发器高度；size 保留月历网格的 large/small 尺寸语义。 */
+    fieldSize?: FieldSize;
     minValue?: Date;
     maxValue?: Date;
     pinnedTimezone?: string;
@@ -1986,6 +2049,17 @@ export declare type ThemeSwitcherProps = {
 
 export declare type ThresholdTone = 'primary' | 'success' | 'warning' | 'danger';
 
+export declare function Timeline({ className, ...props }: TimelineProps): JSX.Element;
+
+export declare function TimelineItem({ tone, indicator, children, className, ...props }: TimelineItemProps): JSX.Element;
+
+export declare type TimelineItemProps = HTMLAttributes<HTMLLIElement> & {
+    tone?: 'neutral' | 'success' | 'danger' | 'warning';
+    indicator?: ReactNode;
+};
+
+export declare type TimelineProps = HTMLAttributes<HTMLOListElement>;
+
 declare type ToastAction = {
     label: string;
     /** 点击后先执行回调再关闭该提示。 */