feat(time): add Time atom component

[FranRubioDev]

Summary

Adds the Time atom component — a segmented time input supporting 12/24h, minute/second granularity, steppers, clock icon, and floating label.

Closes #37

Review scope

• Primary files/areas: src/components/atoms/time/
• Out of scope: i18n locale formatting
• Review workload: large (6 new files, ~1 200 lines)

Type of change

• New component

Workflow gates

• Linked issue is present with Closes #NNN or maintainer approved an exception.
• Linked issue has label status:approved before implementation starts.
• Work was started through the Project flow: assignee set, Project status In progress, branch/worktree recorded.
• PR title follows Conventional Commit format: <type>(<optional scope>): <description>.
• Commits follow the same commitlint-enforced format.
• Diff is focused; unrelated work is called out in Review scope.
• MCP/runtime artifacts are absent: .playwright-mcp, page-*.png, page-*.jpeg, *.md.playwright-output.

Component evidence (required for component changes)

• Validated component spec is linked or quoted in the issue.
• Accessibility contract from the spec was implemented or deviations are explained below.
• Follows the 6-file pattern: types.ts, use*.ts, Component.tsx, Component.test.tsx, Component.stories.tsx, index.ts.
• CVA variants live in types.ts; JSX component has no state, CVA calls, or business logic.
• Public props with runtime defaults have matching @default JSDoc in types.ts (node scripts/verify-prop-default-docs.mjs).
• Uses design tokens from theme.css; no hardcoded colors or arbitrary color utilities.
• Storybook covers default, variants, documented states, edge cases, and dark mode when visually different.
• Component audit result is PASS or accepted PASS WITH WARNINGS.
• Visual review result is included when visuals changed.

Accessibility evidence

• Role/name semantics verified with Testing Library queries or equivalent.
• Keyboard-only behavior verified: Tab / Shift+Tab, Arrow keys, Backspace.
• Focus lifecycle verified: segment focus/blur cycle, container click redirects to hour.
• Disabled, required, invalid/error states expose the expected semantics where applicable.
• Reduced motion behavior is respected where motion changed.
• Screen reader or axe/manual evidence is included below when applicable.

Changes

File	Change
src/components/atoms/time/types.ts	CVA variants, prop types, JSDoc @default tags
src/components/atoms/time/useTime.ts	All logic — segments, keyboard, focus, steppers
src/components/atoms/time/Time.tsx	Presentational component, no state
src/components/atoms/time/Time.stories.tsx	Storybook stories for all variants and states
src/components/atoms/time/Time.test.tsx	Unit tests with Vitest + Testing Library
src/components/atoms/time/index.ts	Public exports

Validation evidence

• TypeScript: pnpm exec tsc --noEmit — passes
• Unit tests: 590 passed (32 test files) including the Time suite
• Build/package: not run (per project convention)
• Storybook or visual check: stories created, pending Storybook visual review
• Accessibility check: keyboard and focus behavior covered in tests
• Security/dependency check: no new dependencies added

[egdev6]

Thanks for the Time atom work. I’d request changes before merge because a few issues currently break the component contract and user-facing behavior.

Blocking items to fix:

• Time is not exported from src/index.ts, so package consumers cannot import it from @stack-and-flow/design-system.
• handleContainerClick refocuses Hours for any click inside the wrapper, so clicking Minutes/Seconds/AM-PM does not keep focus on the clicked segment.
• 12h mode is not safe yet: the AM/PM segment is treated as free text / numeric stepping and can become invalid values like 1 instead of PM.
• onChange can emit stale or unclamped values because the callback uses the raw value/old segment snapshot instead of the normalized next state.
• Storybook docs need to follow the repo convention: JSDoc above const meta and each story, not parameters.docs.description.component.

Please add focused regression tests for segment click focus, AM/PM keyboard/input behavior, and normalized onChange payloads. Also update the PR evidence once the component audit and visual review are addressed.