@astryxdesign/core 0.0.0-bootstrap.0 → 0.0.15

package/src/InputGroup/InputGroupText.tsx

@@ -0,0 +1,112 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file InputGroupText.tsx
+ * @input Uses React, StyleX, theme tokens
+ * @output Exports InputGroupText component
+ * @position Text/icon element rendered inside InputGroup
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/InputGroup/InputGroup.doc.mjs
+ * - /packages/core/src/InputGroup/index.ts
+ * - /packages/cli/templates/blocks/components/InputGroup/
+ */
+
+import React, {type ReactNode} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import type {BaseProps} from '../BaseProps';
+import {
+  colorVars,
+  spacingVars,
+  radiusVars,
+  typographyVars,
+  typeScaleVars,
+  borderVars,
+} from '../theme/tokens.stylex';
+import {mergeProps} from '../utils';
+import {xdsThemeProps} from '../utils/xdsThemeProps';
+
+const styles = stylex.create({
+  text: {
+    display: 'flex',
+    alignItems: 'center',
+    paddingInline: spacingVars['--spacing-2'],
+    backgroundColor: colorVars['--color-background-muted'],
+    fontFamily: typographyVars['--font-family-body'],
+    fontSize: typeScaleVars['--text-body-size'],
+    lineHeight: typeScaleVars['--text-body-leading'],
+    color: colorVars['--color-text-secondary'],
+    whiteSpace: 'nowrap',
+    flexShrink: 0,
+    borderWidth: borderVars['--border-width'],
+    borderStyle: 'solid',
+    borderColor: colorVars['--color-border-emphasized'],
+    marginInlineStart: {
+      default: `calc(-1 * ${borderVars['--border-width']})`,
+      ':first-child': 0,
+    },
+    borderStartStartRadius: {
+      default: 0,
+      ':first-child': radiusVars['--radius-element'],
+    },
+    borderEndStartRadius: {
+      default: 0,
+      ':first-child': radiusVars['--radius-element'],
+    },
+    borderStartEndRadius: {
+      default: 0,
+      ':last-child': radiusVars['--radius-element'],
+    },
+    borderEndEndRadius: {
+      default: 0,
+      ':last-child': radiusVars['--radius-element'],
+    },
+  },
+});
+
+export interface InputGroupTextProps extends BaseProps<HTMLDivElement> {
+  ref?: React.Ref<HTMLDivElement>;
+  /**
+   * Content to render in the text slot.
+   * Can be text or an icon.
+   */
+  children: ReactNode;
+}
+
+/**
+ * A prefix or suffix text element for use inside InputGroup.
+ *
+ * @example
+ * ```
+ * <InputGroup label="URL">
+ *   <InputGroupText>https://</InputGroupText>
+ *   <TextInput label="URL" isLabelHidden value={url} onChange={setUrl} />
+ * </InputGroup>
+ * ```
+ */
+export function InputGroupText({
+  ref,
+  children,
+  xstyle,
+  className,
+  style,
+  ...rest
+}: InputGroupTextProps) {
+  return (
+    <div
+      ref={ref}
+      {...rest}
+      {...mergeProps(
+        xdsThemeProps('input-group-text'),
+        stylex.props(styles.text, xstyle),
+        className,
+        style,
+      )}>
+      {children}
+    </div>
+  );
+}
+
+InputGroupText.displayName = 'InputGroupText';

package/src/InputGroup/groupStyles.ts

@@ -0,0 +1,42 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file groupStyles.ts
+ * @input Uses StyleX, theme tokens
+ * @output Exports shared group-aware styles for input components
+ * @position Shared styles consumed by TextInput, NumberInput when inside an InputGroup
+ */
+
+import * as stylex from '@stylexjs/stylex';
+import {radiusVars, borderVars} from '../theme/tokens.stylex';
+
+export const groupStyles = stylex.create({
+  inGroup: {
+    flex: 1,
+    minWidth: 0,
+    height: '100%',
+    marginInlineStart: {
+      default: `calc(-1 * ${borderVars['--border-width']})`,
+      ':first-child': 0,
+    },
+    borderStartStartRadius: {
+      default: 0,
+      ':first-child': radiusVars['--radius-element'],
+    },
+    borderEndStartRadius: {
+      default: 0,
+      ':first-child': radiusVars['--radius-element'],
+    },
+    borderStartEndRadius: {
+      default: 0,
+      ':last-child': radiusVars['--radius-element'],
+    },
+    borderEndEndRadius: {
+      default: 0,
+      ':last-child': radiusVars['--radius-element'],
+    },
+    ':focus-within': {
+      zIndex: 1,
+    },
+  },
+});

package/src/InputGroup/index.ts

@@ -0,0 +1,18 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file index.ts
+ * @input Imports from InputGroup.tsx, InputGroupText.tsx, InputGroupContext.ts
+ * @output Exports InputGroup, InputGroupText, context hook, and types
+ * @position Component entry point; re-exported by /packages/core/src/index.ts
+ */
+
+export {InputGroup} from './InputGroup';
+export type {InputGroupProps, InputGroupSize} from './InputGroup';
+
+export {InputGroupText} from './InputGroupText';
+export type {InputGroupTextProps} from './InputGroupText';
+
+export {useInputGroup} from './InputGroupContext';

package/src/InteractiveRoleContext/InteractiveRoleContext.ts

@@ -0,0 +1,53 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file InteractiveRoleContext.ts
+ * @input React createContext, use
+ * @output Exports InteractiveRoleContext, useInteractiveRoleContext
+ * @position Context primitive; consumed by useInteractiveRole hook
+ *
+ * Provides a role override to optionally-interactive child components.
+ * When a parent (Popover, DropdownMenu, etc.) needs its child to render
+ * as a button, it wraps the child in this context with role = 'button'.
+ *
+ * Components don't consume this directly — they use `useInteractiveRole`
+ * which checks this context as one of its decision inputs.
+ *
+ * Follows the same pattern as SizeContext:
+ *   SizeContext provides size → useSize resolves it
+ *   InteractiveRoleContext provides role → useInteractiveRole resolves it
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/InteractiveRoleContext/index.ts
+ */
+
+import {createContext, use} from 'react';
+import type {InteractiveRole} from '../hooks/useInteractiveRole';
+
+/**
+ * Context that provides a role override to child components.
+ *
+ * Provided by containers that need their child to be interactive:
+ * - Popover → 'button' (click to open popover)
+ * - DropdownMenu → 'button' (click to open menu)
+ * - Any future component that wraps an optionally-interactive trigger
+ *
+ * `null` means no parent is overriding — resolve based on own props.
+ */
+export const InteractiveRoleContext =
+  createContext<InteractiveRole | null>(null);
+InteractiveRoleContext.displayName = 'InteractiveRoleContext';
+
+/**
+ * Read the role override from context, if any.
+ *
+ * Most components should use `useInteractiveRole` instead of calling
+ * this directly — it incorporates this signal alongside href/onClick.
+ *
+ * @returns The overridden role, or `null` if no parent is providing one.
+ */
+export function useInteractiveRoleContext(): InteractiveRole | null {
+  return use(InteractiveRoleContext);
+}

package/src/InteractiveRoleContext/index.ts

@@ -0,0 +1,15 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file index.ts
+ * @input InteractiveRoleContext
+ * @output Exports InteractiveRoleContext module public API
+ * @position Entry point for InteractiveRoleContext module
+ */
+
+export {
+  InteractiveRoleContext,
+  useInteractiveRoleContext,
+} from './InteractiveRoleContext';

package/src/Item/Item.doc.mjs

@@ -0,0 +1,172 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+  name: 'Item',
+  displayName: 'Item',
+  group: 'Item',
+  category: 'Table & List',
+  isHiddenFromOverview: true,
+  keywords: ["item","list-item","media-object","row","cell","entity","contact","notification","preview"],
+  playground: {
+    defaults: {
+      label: 'Item label',
+      description: 'Supporting text',
+    },
+  },
+  theming: {
+    targets: [
+      {className: 'astryx-item', visualProps: ['density', 'align']},
+    ],
+  },
+  components: [
+    {
+      name: 'Item',
+      displayName: 'Item',
+      description: 'A universal item primitive that unifies the "start content + label + description + end content" layout pattern. Use as a building block for list items, menu items, contact rows, notifications, and more.',
+      props: [
+        {name: 'label', type: 'ReactNode', description: 'Primary text identifying this item. Accepts string (auto-truncated) or ReactNode (for rich content).', required: true},
+        {name: 'marker', type: 'ReactNode', description: 'Marker rendered before startContent as a direct flex child. Use for list bullets/counters that need custom baseline alignment.'},
+        {name: 'startContent', type: 'ReactNode', description: 'Content rendered before the label/description area, such as an icon, avatar, or checkbox.', slotElements: [{__element: 'Avatar', props: {name: 'Ada Lovelace', size: 'xsmall'}}, {__element: 'Icon', props: {icon: 'info', size: 'sm', color: 'secondary'}}]},
+        {name: 'description', type: 'ReactNode', description: 'Secondary text: subtitle, description, or supporting info.'},
+        {name: 'endContent', type: 'ReactNode', description: 'Content rendered after the label/description area, such as badges, metadata, timestamps, or action buttons.', slotElements: [{__element: 'Badge', props: {label: 3}}, {__element: 'Text', props: {color: 'secondary'}, children: '2h ago'}]},
+        {name: 'as', type: "'div' | 'li' | 'span'", description: 'HTML element to render as the root.', default: "'div'"},
+        {name: 'align', type: "'center' | 'start'", description: 'Vertical alignment of start/end content slots.', default: "'center'"},
+        {name: 'density', type: "'compact' | 'balanced' | 'spacious'", description: 'Spacing density. "compact" uses 4px block padding, "balanced" uses 8px, and "spacious" uses 12px block and inline padding.', default: "'balanced'"},
+        {name: 'labelLines', type: 'number', description: 'Max lines before label truncates with ellipsis.'},
+        {name: 'descriptionLines', type: 'number', description: 'Max lines before description truncates with ellipsis.'},
+        {name: 'onClick', type: '(event: MouseEvent) => void', description: 'Click handler. Makes the item clickable with button semantics.'},
+        {name: 'href', type: 'string', description: 'Link URL. Makes the item a link via an invisible anchor element.'},
+        {name: 'target', type: "'_blank' | '_self'", description: 'Link target. Only used with href. target="_blank" automatically adds noopener noreferrer.'},
+        {name: 'rel', type: 'string', description: 'Link relationship tokens. noopener noreferrer are merged automatically for target="_blank".'},
+        {name: 'isHighlighted', type: 'boolean', description: 'Highlighted state (hover/keyboard focus appearance).', default: 'false'},
+        {name: 'isSelected', type: 'boolean', description: 'Selected state.', default: 'false'},
+        {name: 'isDisabled', type: 'boolean', description: 'Disabled state.', default: 'false'},
+        {name: 'ref', type: 'React.Ref<HTMLDivElement>', description: 'Ref forwarded to the root element.'},
+        {name: 'xstyle', type: 'StyleXStyles', description: 'StyleX styles for layout customization. Must be a stylex.create() value.'},
+        {name: 'data-testid', type: 'string', description: 'Test selector for automated testing frameworks.'},
+      ],
+    },
+  ],
+  usage: {
+    description:
+      'A single, flexible item primitive that unifies the "start content + label + description + end content" pattern across XDS. Use it wherever you need a structured row: dropdown menus, selectors, contact lists, notifications, file browsers, and activity feeds.',
+    bestPractices: [
+      {guidance: true, description: 'Use named slots (startContent, label, description, endContent) for the common layout. These cover the 80% case.'},
+      {guidance: true, description: 'Use density="compact" for menus and dense lists, "balanced" for standard rows, and "spacious" for roomier layouts.'},
+      {guidance: true, description: 'Set labelLines and descriptionLines to control truncation when content length varies.'},
+      {guidance: true, description: 'Use align="start" when start or end content is taller than a single line of text.'},
+      {guidance: false, description: "Don't nest interactive elements (buttons, links) inside an interactive Item; it creates confusing focus and click targets."},
+      {guidance: false, description: "Don't use Item for navigation between views; use proper navigation components instead."},
+      {guidance: false, description: "Don't add read/unread or inbox-specific behavior directly; compose a thin wrapper like PreviewItem instead."},
+    ],
+    anatomy: [
+      {name: 'Marker', required: false, description: 'Optional list bullet/counter rendered before start content.'},
+      {name: 'Start content', required: false, description: 'Leading visual: avatar, icon, image, or checkbox.'},
+      {name: 'Label', required: true, description: 'Primary text identifying the item.'},
+      {name: 'Description', required: false, description: 'Secondary supporting text below the label.'},
+      {name: 'End content', required: false, description: 'End-aligned content: badges, timestamps, or action buttons.'},
+    ],
+  },
+};
+
+/** @type {import('../docs-types').TranslationDoc} */
+export const docsZh = {
+  components: [
+    {
+      name: 'Item',
+      displayName: 'Item',
+      description: '通用项目原语，统一 "起始内容 + 标签 + 描述 + 结束内容" 布局模式。用作列表项、菜单项、联系人行、通知等的构建块。',
+      propDescriptions: {
+        label: '标识此项目的主要文本。接受字符串（自动截断）或 ReactNode（用于富内容）。',
+        marker: '在 startContent 之前渲染的标记，作为直接 flex 子元素。用于需要自定义基线对齐的列表项目符号/计数器。',
+        startContent: '在标签/描述区域之前渲染的内容，例如图标、头像或复选框。',
+        description: '次要文本：副标题、描述或辅助信息。',
+        endContent: '在标签/描述区域之后渲染的内容，例如徽章、元数据、时间戳或操作按钮。',
+        as: '根元素的 HTML 元素。',
+        align: '起始/结束内容插槽的垂直对齐方式。',
+        density: '间距密度。"compact" 使用 4px 块内距，"balanced" 使用 8px，"spacious" 使用 12px 块内距和内联内距。',
+        labelLines: '标签截断前的最大行数。',
+        descriptionLines: '描述截断前的最大行数。',
+        onClick: '点击处理函数。使项目可点击，具有按钮语义。',
+        href: '链接 URL。通过不可见锚点元素使项目成为链接。',
+        target: '链接目标。仅与 href 一起使用。target="_blank" 会自动添加 noopener noreferrer。',
+        rel: '链接关系标记。target="_blank" 会自动合并 noopener noreferrer。',
+        isHighlighted: '高亮状态（悬停/键盘焦点外观）。',
+        isSelected: '选中状态。',
+        isDisabled: '禁用状态。',
+        ref: '转发到根元素的引用。',
+        xstyle: 'StyleX 样式，用于布局自定义。必须是 stylex.create() 的值。',
+        'data-testid': '自动化测试的选择器。',
+      },
+    },
+  ],
+  usage: {
+    description:
+      '通用项目原语，统一 XDS 中 "起始内容 + 标签 + 描述 + 结束内容" 的布局模式。适用于下拉菜单、选择器、联系人列表、通知、文件浏览器和活动流等场景。',
+    bestPractices: [
+      {guidance: true, description: '使用命名插槽（startContent、label、description、endContent）处理常见布局。'},
+      {guidance: true, description: '菜单和密集列表使用 density="compact"，标准行使用 "balanced"，宽松布局使用 "spacious"。'},
+      {guidance: true, description: '设置 labelLines 和 descriptionLines 控制内容长度不定时的截断。'},
+      {guidance: true, description: '当起始或结束内容高于单行文本时使用 align="start"。'},
+      {guidance: false, description: '不要在交互式 Item 内嵌套交互元素（按钮、链接）。'},
+      {guidance: false, description: '不要使用 Item 进行视图间导航：使用适当的导航组件。'},
+      {guidance: false, description: '不要直接添加已读/未读行为：组合一个薄包装器如 PreviewItem。'},
+    ],
+    anatomy: [
+      {name: '标记', required: false, description: '在起始内容之前渲染的可选列表项目符号/计数器。'},
+      {name: '起始内容', required: false, description: '前导视觉：头像、图标、图片或复选框。'},
+      {name: '标签', required: true, description: '标识项目的主要文本。'},
+      {name: '描述', required: false, description: '标签下方的次要辅助文本。'},
+      {name: '结束内容', required: false, description: '末端对齐内容：徽章、时间戳或操作按钮。'},
+    ],
+  },
+};
+
+/** @type {import('../docs-types').TranslationDoc} */
+export const docsDense = {
+  description: 'universal item primitive w/ startContent+label+description+endContent layout. building block for list items, menu items, contacts, notifications',
+  usage: {
+    description:
+      'Flexible item primitive unifying the "start content + label + description + end content" pattern. Use for structured rows in menus, lists, contacts, notifications, file browsers.',
+    bestPractices: [
+      {guidance: true, description: 'Named slots (startContent, label, description, endContent) for the 80% case.'},
+      {guidance: true, description: 'density="compact" for menus/dense lists, "balanced" for standard rows, "spacious" for roomier layouts.'},
+      {guidance: true, description: 'labelLines/descriptionLines for truncation control.'},
+      {guidance: true, description: 'align="start" when start/end content is taller than one text line.'},
+      {guidance: false, description: "Don't nest interactive elements inside interactive Item."},
+      {guidance: false, description: "Don't use for view navigation; use nav components."},
+      {guidance: false, description: "Don't add inbox-specific behavior; compose a wrapper."},
+    ],
+  },
+  components: [
+    {
+      name: 'Item',
+      displayName: 'Item',
+      description: 'universal item primitive w/ startContent+label+description+endContent layout',
+      propDescriptions: {
+        label: 'Primary text. String auto-truncates; ReactNode for rich content.',
+        marker: 'List bullet/counter before startContent as direct flex child.',
+        startContent: 'Content before label/description: avatar, icon, checkbox, ReactNode.',
+        description: 'Secondary text below label.',
+        endContent: 'Content after label/description: badges, timestamps, actions.',
+        as: 'Root HTML element.',
+        align: 'Vertical alignment of start/end content slots.',
+        density: 'Spacing: "compact" (4px), "balanced" (8px), or "spacious" (12px).',
+        labelLines: 'Max label lines before truncation.',
+        descriptionLines: 'Max description lines before truncation.',
+        onClick: 'Click handler; enables button semantics.',
+        href: 'Link URL; enables anchor semantics.',
+        target:
+          'Link target, only with href. target="_blank" auto-adds noopener noreferrer.',
+        rel: 'Link relationship tokens. noopener noreferrer are merged for target="_blank".',
+        isHighlighted: 'Highlighted state.',
+        isSelected: 'Selected state.',
+        isDisabled: 'Disabled state.',
+        xstyle: 'StyleX layout styles; must be stylex.create() value.',
+        'data-testid': 'Test selector.',
+      },
+    },
+  ],
+};