@fragments-sdk/ui 0.3.0 → 0.4.0

package/src/components/Progress/Progress.module.scss

@@ -41,17 +41,17 @@
   border-radius: var(--fui-radius-full, $fui-radius-full);
 }
 
-// Size variants for track
+// Size variants for track (using closest 7px grid values)
 .trackSm {
-  height: 4px;
+  height: calc(var(--fui-space-1, $fui-space-1) / 2); // ~3.5px
 }
 
 .trackMd {
-  height: 8px;
+  height: var(--fui-space-1, $fui-space-1); // 7px
 }
 
 .trackLg {
-  height: 12px;
+  height: var(--fui-space-2, $fui-space-2); // 14px
 }
 
 // Indicator (filled portion)
@@ -160,10 +160,10 @@
   font-variant-numeric: tabular-nums;
 }
 
-// Size variants for circular
+// Size variants for circular (using closest 7px grid values)
 .circularSm {
-  width: 32px;
-  height: 32px;
+  width: var(--fui-space-4, $fui-space-4); // 28px
+  height: var(--fui-space-4, $fui-space-4);
 
   .circularValue {
     font-size: var(--fui-font-size-xs, $fui-font-size-xs);
@@ -171,13 +171,13 @@
 }
 
 .circularMd {
-  width: 48px;
-  height: 48px;
+  width: var(--fui-space-6, $fui-space-6); // 42px
+  height: var(--fui-space-6, $fui-space-6);
 }
 
 .circularLg {
-  width: 64px;
-  height: 64px;
+  width: var(--fui-space-8, $fui-space-8); // 56px
+  height: var(--fui-space-8, $fui-space-8);
 
   .circularValue {
     font-size: var(--fui-font-size-base, $fui-font-size-base);

package/src/components/Progress/index.tsx

@@ -8,7 +8,7 @@ import '../../styles/globals.scss';
 // Types
 // ============================================
 
-export interface ProgressProps {
+export interface ProgressProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'defaultValue'> {
   /** Current progress value (0-100). Null for indeterminate. */
   value?: number | null;
   /** Minimum value */
@@ -25,11 +25,9 @@ export interface ProgressProps {
   showValue?: boolean;
   /** Custom value formatter */
   formatValue?: (value: number) => string;
-  /** Additional class name */
-  className?: string;
 }
 
-export interface CircularProgressProps {
+export interface CircularProgressProps extends React.HTMLAttributes<HTMLDivElement> {
   /** Current progress value (0-100). Null for indeterminate. */
   value?: number | null;
   /** Size of the circular progress */
@@ -40,8 +38,6 @@ export interface CircularProgressProps {
   showValue?: boolean;
   /** Stroke width */
   strokeWidth?: number;
-  /** Additional class name */
-  className?: string;
 }
 
 // ============================================
@@ -58,6 +54,9 @@ export function Progress({
   showValue = false,
   formatValue,
   className,
+  'aria-label': ariaLabel,
+  'aria-valuetext': ariaValueText,
+  ...htmlProps
 }: ProgressProps) {
   const isIndeterminate = value === null;
   const percentage = isIndeterminate ? 0 : Math.round(((value - min) / (max - min)) * 100);
@@ -83,12 +82,21 @@ export function Progress({
     ? formatValue(percentage)
     : `${percentage}%`;
 
+  // Default value text for screen readers
+  const effectiveValueText = ariaValueText || (
+    isIndeterminate ? 'Loading' : `${percentage} percent`
+  );
+
   return (
     <BaseProgress.Root
+      {...htmlProps}
       value={value}
       min={min}
       max={max}
       className={rootClasses}
+      aria-label={ariaLabel || (label ? undefined : 'Progress')}
+      aria-valuetext={effectiveValueText}
+      aria-busy={isIndeterminate}
     >
       {(label || showValue) && (
         <div className={styles.header}>
@@ -129,6 +137,10 @@ export function CircularProgress({
   showValue = false,
   strokeWidth: customStrokeWidth,
   className,
+  'aria-label': ariaLabel,
+  'aria-labelledby': ariaLabelledBy,
+  'aria-valuetext': ariaValueText,
+  ...htmlProps
 }: CircularProgressProps) {
   const isIndeterminate = value === null;
   const percentage = isIndeterminate ? 0 : Math.min(100, Math.max(0, value));
@@ -156,17 +168,32 @@ export function CircularProgress({
     .filter(Boolean)
     .join(' ');
 
+  // Default value text for screen readers
+  const effectiveValueText = ariaValueText || (
+    isIndeterminate ? 'Loading' : `${Math.round(percentage)} percent`
+  );
+
   return (
     <BaseProgress.Root
+      {...htmlProps}
       value={value}
+      min={0}
+      max={100}
       className={rootClasses}
+      aria-label={ariaLabel}
+      aria-labelledby={ariaLabelledBy}
       aria-valuenow={isIndeterminate ? undefined : percentage}
+      aria-valuemin={0}
+      aria-valuemax={100}
+      aria-valuetext={effectiveValueText}
+      aria-busy={isIndeterminate}
     >
       <svg
         className={styles.circularSvg}
         width={svgSize}
         height={svgSize}
         viewBox={`0 0 ${svgSize} ${svgSize}`}
+        aria-hidden="true"
       >
         {/* Track circle */}
         <circle
@@ -189,7 +216,7 @@ export function CircularProgress({
         />
       </svg>
       {showValue && !isIndeterminate && (
-        <span className={styles.circularValue}>{Math.round(percentage)}%</span>
+        <span className={styles.circularValue} aria-hidden="true">{Math.round(percentage)}%</span>
       )}
     </BaseProgress.Root>
   );

package/src/components/Prompt/Prompt.fragment.tsx

@@ -0,0 +1,231 @@
+import React from 'react';
+import { defineSegment } from '@fragments/core';
+import { Prompt } from './index.js';
+
+export default defineSegment({
+  component: Prompt,
+
+  meta: {
+    name: 'Prompt',
+    description: 'Multi-line input with toolbar for AI/chat interfaces',
+    category: 'forms',
+    status: 'stable',
+    tags: ['prompt', 'chat', 'ai', 'input', 'textarea', 'form'],
+  },
+
+  usage: {
+    when: [
+      'Building chat or AI assistant interfaces',
+      'Need multi-line input with submit action',
+      'Require toolbar with actions like attachments or model selection',
+    ],
+    whenNot: [
+      'Simple single-line text input (use Input)',
+      'Basic multi-line without toolbar (use Textarea)',
+      'Search-only interface (use Input with search variant)',
+    ],
+    guidelines: [
+      'Always provide an onSubmit handler',
+      'Use loading state during API calls',
+      'Consider showing usage/token limits for AI contexts',
+    ],
+    accessibility: [
+      'Enter submits, Shift+Enter for newline',
+      'Submit button is keyboard accessible',
+      'Loading state prevents duplicate submissions',
+    ],
+  },
+
+  props: {
+    value: {
+      type: 'string',
+      description: 'Controlled input value',
+    },
+    defaultValue: {
+      type: 'string',
+      description: 'Uncontrolled default value',
+    },
+    onChange: {
+      type: 'function',
+      description: 'Called when value changes',
+    },
+    onSubmit: {
+      type: 'function',
+      description: 'Called on form submission',
+    },
+    placeholder: {
+      type: 'string',
+      default: '"Ask, Search or Chat..."',
+      description: 'Placeholder text for the textarea',
+    },
+    disabled: {
+      type: 'boolean',
+      default: 'false',
+      description: 'Disable the entire prompt',
+    },
+    loading: {
+      type: 'boolean',
+      default: 'false',
+      description: 'Show loading state',
+    },
+    minRows: {
+      type: 'number',
+      default: '1',
+      description: 'Minimum number of visible rows',
+    },
+    maxRows: {
+      type: 'number',
+      default: '8',
+      description: 'Maximum number of visible rows',
+    },
+    autoResize: {
+      type: 'boolean',
+      default: 'true',
+      description: 'Enable auto-resize based on content',
+    },
+    submitOnEnter: {
+      type: 'boolean',
+      default: 'true',
+      description: 'Submit on Enter (Shift+Enter for newline)',
+    },
+  },
+
+  relations: [
+    {
+      component: 'Input',
+      relationship: 'alternative',
+      note: 'Use Input for simple single-line text input',
+    },
+    {
+      component: 'Textarea',
+      relationship: 'alternative',
+      note: 'Use Textarea for multi-line without toolbar',
+    },
+  ],
+
+  contract: {
+    propsSummary: [
+      'value: string - controlled input value',
+      'onSubmit: (value: string) => void - submission handler',
+      'placeholder: string - hint text (default: "Ask, Search or Chat...")',
+      'disabled: boolean - disables interaction',
+      'loading: boolean - shows loading state',
+      'minRows/maxRows: number - row constraints (default: 1/8)',
+      'submitOnEnter: boolean - Enter key behavior (default: true)',
+    ],
+    scenarioTags: [
+      'form.prompt',
+      'form.chat',
+      'form.ai',
+      'ui.chat-input',
+    ],
+    a11yRules: [
+      'A11Y_TEXTAREA_LABEL',
+      'A11Y_BUTTON_LABEL',
+    ],
+    bans: [],
+  },
+
+  variants: [
+    {
+      name: 'Basic',
+      description: 'Simple prompt with submit button',
+      render: () => (
+        <Prompt onSubmit={(value) => console.log(value)}>
+          <Prompt.Textarea />
+          <Prompt.Toolbar>
+            <Prompt.Actions />
+            <Prompt.Info>
+              <Prompt.Submit />
+            </Prompt.Info>
+          </Prompt.Toolbar>
+        </Prompt>
+      ),
+    },
+    {
+      name: 'With Actions',
+      description: 'Prompt with attachment and mode buttons',
+      render: () => (
+        <Prompt onSubmit={(value) => console.log(value)}>
+          <Prompt.Textarea />
+          <Prompt.Toolbar>
+            <Prompt.Actions>
+              <Prompt.ActionButton aria-label="Add attachment">
+                +
+              </Prompt.ActionButton>
+              <Prompt.ModeButton>Auto</Prompt.ModeButton>
+            </Prompt.Actions>
+            <Prompt.Info>
+              <Prompt.Submit />
+            </Prompt.Info>
+          </Prompt.Toolbar>
+        </Prompt>
+      ),
+    },
+    {
+      name: 'With Usage',
+      description: 'Shows token usage indicator',
+      render: () => (
+        <Prompt onSubmit={(value) => console.log(value)}>
+          <Prompt.Textarea />
+          <Prompt.Toolbar>
+            <Prompt.Actions>
+              <Prompt.ActionButton aria-label="Add attachment">
+                +
+              </Prompt.ActionButton>
+              <Prompt.ModeButton active>Auto</Prompt.ModeButton>
+            </Prompt.Actions>
+            <Prompt.Info>
+              <Prompt.Usage>52% used</Prompt.Usage>
+              <Prompt.Submit />
+            </Prompt.Info>
+          </Prompt.Toolbar>
+        </Prompt>
+      ),
+    },
+    {
+      name: 'Loading State',
+      description: 'During API submission',
+      render: () => (
+        <Prompt
+          onSubmit={(value) => console.log(value)}
+          loading
+          defaultValue="Tell me about the weather..."
+        >
+          <Prompt.Textarea />
+          <Prompt.Toolbar>
+            <Prompt.Actions>
+              <Prompt.ActionButton aria-label="Add attachment">
+                +
+              </Prompt.ActionButton>
+              <Prompt.ModeButton>Auto</Prompt.ModeButton>
+            </Prompt.Actions>
+            <Prompt.Info>
+              <Prompt.Usage>52% used</Prompt.Usage>
+              <Prompt.Submit />
+            </Prompt.Info>
+          </Prompt.Toolbar>
+        </Prompt>
+      ),
+    },
+    {
+      name: 'Disabled',
+      description: 'Non-interactive prompt',
+      render: () => (
+        <Prompt onSubmit={(value) => console.log(value)} disabled>
+          <Prompt.Textarea />
+          <Prompt.Toolbar>
+            <Prompt.Actions>
+              <Prompt.ActionButton aria-label="Add attachment">
+                +
+              </Prompt.ActionButton>
+            </Prompt.Actions>
+            <Prompt.Info>
+              <Prompt.Submit />
+            </Prompt.Info>
+          </Prompt.Toolbar>
+        </Prompt>
+      ),
+    },
+  ],
+});

package/src/components/Prompt/Prompt.module.scss

@@ -0,0 +1,243 @@
+@use '../../tokens/variables' as *;
+@use '../../tokens/mixins' as *;
+
+// ============================================
+// Prompt Root
+// ============================================
+
+.prompt {
+  @include surface-elevated;
+  display: flex;
+  flex-direction: column;
+  border-radius: var(--fui-radius-xl, $fui-radius-xl);
+  overflow: hidden;
+
+  &[data-disabled] {
+    opacity: 0.5;
+    pointer-events: none;
+  }
+}
+
+// Fixed variant - for viewport-fixed prompts (centered to page)
+.fixed {
+  position: fixed;
+  bottom: var(--fui-space-4, $fui-space-4);
+  left: 50%;
+  transform: translateX(-50%);
+  width: calc(100% - var(--fui-space-8, $fui-space-8));
+  max-width: 800px;
+  z-index: 100;
+  box-shadow:
+    0 -4px 16px rgba(0, 0, 0, 0.08),
+    0 4px 24px rgba(0, 0, 0, 0.12);
+}
+
+// Sticky variant - for content-area fixed prompts (accounts for sidebar)
+// Use --fui-prompt-inset-left CSS variable to offset from sidebar
+.sticky {
+  position: fixed;
+  bottom: var(--fui-space-4, $fui-space-4);
+  left: var(--fui-prompt-inset-left, 0);
+  right: 0;
+  margin-left: auto;
+  margin-right: auto;
+  width: calc(100% - var(--fui-prompt-inset-left, 0px) - var(--fui-space-8, $fui-space-8));
+  max-width: 800px;
+  z-index: 100;
+  box-shadow:
+    0 -4px 16px rgba(0, 0, 0, 0.08),
+    0 4px 24px rgba(0, 0, 0, 0.12);
+
+  // Center within the available space (after sidebar)
+  left: calc(var(--fui-prompt-inset-left, 0px) + ((100% - var(--fui-prompt-inset-left, 0px)) / 2));
+  transform: translateX(-50%);
+}
+
+// ============================================
+// Textarea
+// ============================================
+
+.textarea {
+  @include button-reset;
+  @include text-base;
+
+  display: block;
+  width: 100%;
+  min-height: 2.857rem; // ~40px
+  padding: var(--fui-space-2, $fui-space-2) var(--fui-space-3, $fui-space-3);
+  background: transparent;
+  border: none;
+  resize: none;
+  overflow-y: auto;
+  line-height: $fui-line-height-normal;
+
+  &::placeholder {
+    color: var(--fui-text-tertiary, $fui-text-tertiary);
+  }
+
+  &:focus {
+    outline: none;
+  }
+
+  &:disabled {
+    cursor: not-allowed;
+  }
+}
+
+// ============================================
+// Toolbar
+// ============================================
+
+.toolbar {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--fui-space-2, $fui-space-2);
+  padding: var(--fui-space-1, $fui-space-1) var(--fui-space-2, $fui-space-2);
+  background-color: var(--fui-bg-secondary, $fui-bg-secondary);
+  border-top: 1px solid var(--fui-border, $fui-border);
+}
+
+// ============================================
+// Actions & Info
+// ============================================
+
+.actions {
+  display: flex;
+  align-items: center;
+  gap: var(--fui-space-1, $fui-space-1);
+}
+
+.info {
+  display: flex;
+  align-items: center;
+  gap: var(--fui-space-2, $fui-space-2);
+}
+
+// ============================================
+// Action Button (circular, e.g. "+")
+// ============================================
+
+.actionButton {
+  @include button-reset;
+  @include interactive-base;
+
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 2rem;
+  height: 2rem;
+  border-radius: var(--fui-radius-full, $fui-radius-full);
+  background-color: var(--fui-bg-tertiary, $fui-bg-tertiary);
+  color: var(--fui-text-primary, $fui-text-primary);
+  font-size: var(--fui-font-size-sm, $fui-font-size-sm);
+
+  &:hover:not(:disabled) {
+    background-color: var(--fui-bg-hover, $fui-bg-hover);
+  }
+
+  &:active:not(:disabled) {
+    background-color: var(--fui-bg-active, $fui-bg-active);
+  }
+
+  svg {
+    width: 1rem;
+    height: 1rem;
+  }
+}
+
+// ============================================
+// Mode Button (text button, e.g. "Auto")
+// ============================================
+
+.modeButton {
+  @include button-reset;
+  @include interactive-base;
+
+  display: flex;
+  align-items: center;
+  gap: var(--fui-space-1, $fui-space-1);
+  padding: var(--fui-space-1, $fui-space-1) var(--fui-space-2, $fui-space-2);
+  border-radius: var(--fui-radius-md, $fui-radius-md);
+  background-color: transparent;
+  color: var(--fui-text-secondary, $fui-text-secondary);
+  font-size: var(--fui-font-size-xs, $fui-font-size-xs);
+  font-weight: var(--fui-font-weight-medium, $fui-font-weight-medium);
+
+  &:hover:not(:disabled) {
+    background-color: var(--fui-bg-hover, $fui-bg-hover);
+    color: var(--fui-text-primary, $fui-text-primary);
+  }
+
+  &:active:not(:disabled) {
+    background-color: var(--fui-bg-active, $fui-bg-active);
+  }
+}
+
+.modeButtonActive {
+  color: var(--fui-text-primary, $fui-text-primary);
+  background-color: var(--fui-bg-tertiary, $fui-bg-tertiary);
+}
+
+// ============================================
+// Usage indicator
+// ============================================
+
+.usage {
+  @include helper-text;
+  white-space: nowrap;
+}
+
+// ============================================
+// Submit Button
+// ============================================
+
+.submit {
+  @include button-reset;
+  @include interactive-base;
+
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 2rem;
+  height: 2rem;
+  border-radius: var(--fui-radius-full, $fui-radius-full);
+  background-color: var(--fui-color-accent, $fui-color-accent);
+  color: var(--fui-text-inverse, $fui-text-inverse);
+
+  &:hover:not(:disabled) {
+    background-color: var(--fui-color-accent-hover, $fui-color-accent-hover);
+  }
+
+  &:active:not(:disabled) {
+    background-color: var(--fui-color-accent-active, $fui-color-accent-active);
+  }
+
+  &:disabled {
+    opacity: 0.5;
+    cursor: not-allowed;
+  }
+
+  svg {
+    width: 1rem;
+    height: 1rem;
+  }
+}
+
+.submitLoading {
+  position: relative;
+
+  svg {
+    animation: pulse 1s ease-in-out infinite;
+  }
+}
+
+@keyframes pulse {
+  0%,
+  100% {
+    opacity: 1;
+  }
+  50% {
+    opacity: 0.5;
+  }
+}