Repository navigation
chore: replace left/right prop values with start/end - #85
LinKCoding wants to merge 10 commits into
Conversation
@skillsoft/eslint-plugin-gamut
@skillsoft/gamut
@skillsoft/gamut-agent-tools
@skillsoft/gamut-codemods
@skillsoft/gamut-icons
@skillsoft/gamut-illustrations
@skillsoft/gamut-patterns
@skillsoft/gamut-styles
@skillsoft/gamut-tests
@skillsoft/variance
commit: |
Codecov Report❌ Patch coverage is Additional details and impacted files@@ Coverage Diff @@
## main #85 +/- ##
=======================================
Coverage 77.20% 77.20%
=======================================
Files 464 464
Lines 32091 32093 +2
Branches 1535 1630 +95
=======================================
+ Hits 24776 24778 +2
Misses 7307 7307
Partials 8 8
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
Directional props now use logical `start` / `end` values instead of physical `left` / `right`. - Disclosure `buttonPlacement` - Drawer `alignContentContainer` - Flyout `openFrom` - SelectDropdown `menuAlignment` - DataList column, ListCol, and FilterControl `justify` - Toggle `labelSide` - `iconPosition` on FillButton, StrokeButton, TextButton, Anchor, Tag, and Badge - GridForm section `layout` and `submit.position` Stories, docs, and agent skills are updated to match. Code Connect files keep `left` / `right` with TODO comments until the Figma changes take effect. BREAKING CHANGE: `left` and `right` are no longer accepted for these props. Use `start` in place of `left` and `end` in place of `right`. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… PopoverContainer, and Tips Popover, PopoverContainer, and Tips alignment values now use logical `start` / `end` instead of physical `left` / `right`. - Popover `align` and `beak` (also Coachmark `beak`): `start` | `end` | `center` - PopoverContainer `alignment`: `top-start`, `top-end`, `bottom-start`, `bottom-end`, `top`, `bottom`, `start`, `end` - ToolTip, InfoTip, and PreviewTip `alignment` (and Modal `tipAlignment`): `top-start`, `top-end`, `bottom-start`, `bottom-end`, `start-center`, `end-center`, `top-center`, `bottom-center` PopoverContainer resolves logical alignments to physical ones with `resolvePhysicalAlignment`, which replaces `mirrorAlignment`. Popover's `resolveHorizontalSideForRtl` now takes `start` / `end` and returns a physical side. Internal beak variant keys use `start` / `end`; pattern variants and beak rotations stay physical. Stories, tests, docs, and agent skills are updated to match. Code Connect files keep their current values with TODO comments until the Figma changes take effect. This also fixes two GridForm docs lines missed in the previous commit. BREAKING CHANGE: `left` and `right` are no longer accepted in these alignment values. Use `start` in place of `left` and `end` in place of `right`, e.g. `top-left` becomes `top-start` and `right-center` becomes `end-center`. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Physical `left` / `right` CSS keyword values now use logical `start` / `end`, so they flip in RTL. - SelectDropdown option label `textAlign` - DataList SortControl `textAlign` - ProgressBar percent label `text-align` - BarChart and Menu story alignment - Storybook TableOfContents and ImageGallery `textAlign` LTR rendering is unchanged. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The naming conventions rationale page now explains why prop values use `start` / `end` instead of `left` / `right`, and why `start` / `end` is preferred over `leading` / `trailing` for values. The writing guidance page links to the rationale page and updates the RTL rule to cover prop values. The rule no longer says `start` / `end` replace `top` / `bottom`, which contradicted the renamed values. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The "Staying correct in both reading directions" section now explains the `start` / `end` values Gamut uses and why, then the `left` / `right` values they replaced and why those no longer suit RTL layouts. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
7f9cd93 to
9775597
Compare
There was a problem hiding this comment.
🟡 Changes recommended
Storybook type summaries still advertise removed physical alignment values for InfoTip and Coachmark, contradicting the migrated controls and accepted prop values.
3 open issues
What changed in this PR
This PR replaces physical left/right prop values with logical start/end values across Gamut, making the API names match reading-direction-aware placement. This is a breaking change with no legacy aliases; consuming-app migration is planned separately.
Changes:
- Updates component types, defaults, placement helpers, and selected CSS alignment values.
- Migrates stories and existing positioning tests to the logical values.
- Updates documentation and agent skills; adds TODO comments without changing Code Connect mappings.
| File | Description |
|---|---|
packages/styleguide/src/lib/Meta/Deep Controls add-on.mdx |
Migrates InfoTip control examples. |
packages/styleguide/.storybook/components/Navigation/TableOfContents.tsx |
Uses logical text alignment. |
packages/styleguide/.storybook/components/Elements/ImageGallery.tsx |
Aligns image labels to start. |
packages/styleguide/.storybook/components/Elements/ComponentSource.tsx |
Places source-link icons at end. |
packages/styleguide/.storybook/argTypes/infotip.tsx |
Migrates InfoTip controls and default. |
packages/styleguide/.storybook/argTypes/closeButtonProps.tsx |
Migrates tooltip alignment options. |
packages/gamut/src/Toggle/types.tsx |
Changes label-side values. |
packages/gamut/src/Toggle/Toggle.stories.tsx |
Renames label-side examples. |
packages/gamut/src/Toggle/index.tsx |
Migrates label placement logic. |
packages/gamut/src/Toggle/elements.tsx |
Renames the label-end styling state. |
packages/gamut/src/Tips/ToolTip/ToolTip.stories.tsx |
Migrates tooltip placements. |
packages/gamut/src/Tips/shared/types.tsx |
Defines logical tip alignment values. |
packages/gamut/src/Tips/shared/styles/composeVariantsUtils.ts |
Matches logical alignment variants. |
packages/gamut/src/Tips/shared/popoverAlignmentUtils.ts |
Maps logical tips to popover placements. |
packages/gamut/src/Tips/shared/popoverAlignmentUtils.test.ts |
Updates alignment mapping assertions. |
packages/gamut/src/Tips/PreviewTip/styles.ts |
Recognizes logical shadow alignment names. |
packages/gamut/src/Tips/PreviewTip/PreviewTip.stories.tsx |
Migrates preview placements. |
packages/gamut/src/Tips/PreviewTip/index.tsx |
Defaults alignment to top-end. |
packages/gamut/src/Tips/InfoTip/InfoTip.stories.tsx |
Migrates placements and interaction selectors. |
packages/gamut/src/Tips/InfoTip/index.tsx |
Defaults alignment to top-end. |
packages/gamut/src/Tag/index.tsx |
Uses start-positioned icons. |
packages/gamut/src/ProgressBar/index.tsx |
Aligns percent text to end. |
packages/gamut/src/PopoverContainer/utils.ts |
Resolves logical placements to physical coordinates. |
packages/gamut/src/PopoverContainer/types.ts |
Separates logical and physical alignment types. |
packages/gamut/src/PopoverContainer/PopoverContainer.tsx |
Defaults placement to bottom-start. |
packages/gamut/src/PopoverContainer/PopoverContainer.test.tsx |
Migrates positioning and RTL test inputs. |
packages/gamut/src/PopoverContainer/PopoverContainer.stories.tsx |
Migrates placement examples. |
packages/gamut/src/Popover/utils.ts |
Resolves logical horizontal sides. |
packages/gamut/src/Popover/utils.test.ts |
Updates side-resolution test inputs. |
packages/gamut/src/Popover/types.tsx |
Migrates alignment and beak contracts. |
packages/gamut/src/Popover/styles/beak.ts |
Renames beak variants and matching logic. |
packages/gamut/src/Popover/styles/beak.test.ts |
Updates beak variant assertions. |
packages/gamut/src/Popover/Popover.tsx |
Migrates default alignment and resolution. |
packages/gamut/src/Popover/Popover.stories.tsx |
Migrates placement and RTL examples. |
packages/gamut/src/Popover/elements.tsx |
Keeps internal positioning types physical. |
packages/gamut/src/Patterns/FloatingMenu/FloatingMenu.stories.tsx |
Migrates menu placement. |
packages/gamut/src/Menu/MenuItem.stories.tsx |
Uses logical tooltip placement. |
packages/gamut/src/Menu/Menu.stories.tsx |
Migrates tooltip, popover, and CSS alignments. |
packages/gamut/src/List/ListRow.stories.tsx |
Uses end-justified columns. |
packages/gamut/src/List/ListCol.stories.tsx |
Migrates justification examples and assertions. |
packages/gamut/src/List/List.stories.tsx |
Migrates control-column justification. |
packages/gamut/src/List/elements.tsx |
Renames column justification variants. |
packages/gamut/src/helpers/appendIconToContent.tsx |
Migrates shared icon positioning. |
packages/gamut/src/GridForm/Usage.stories.tsx |
Migrates submit-position controls. |
packages/gamut/src/GridForm/types.ts |
Changes section layout to start. |
packages/gamut/src/GridForm/States.stories.tsx |
Migrates submit positioning. |
packages/gamut/src/GridForm/Layout.stories.tsx |
Migrates section and InfoTip placements. |
packages/gamut/src/GridForm/GridFormButtons/index.tsx |
Migrates button-position lookup and default. |
packages/gamut/src/GridForm/Fields.stories.tsx |
Migrates submit positioning. |
packages/gamut/src/GridForm/Buttons.stories.tsx |
Migrates button placement examples. |
packages/gamut/src/Form/inputs/SelectDropdown/types/styles.ts |
Changes menu-alignment values. |
packages/gamut/src/Form/inputs/SelectDropdown/SelectDropdown.tsx |
Defaults menu alignment to start. |
packages/gamut/src/Form/inputs/SelectDropdown/SelectDropdown.stories.tsx |
Demonstrates end-aligned menus. |
packages/gamut/src/Form/inputs/SelectDropdown/elements/options.tsx |
Aligns secondary option text to end. |
packages/gamut/src/Form/inputs/SelectDropdown/core/styles.ts |
Uses logical insets for end alignment. |
packages/gamut/src/Form/elements/FormGroup.stories.tsx |
Migrates InfoTip placements. |
packages/gamut/src/FocusTrap/FocusTrap.stories.tsx |
Migrates form submit placement. |
packages/gamut/src/Flyout/index.tsx |
Migrates opening-edge values and mapping. |
packages/gamut/src/Drawer/index.tsx |
Migrates content-edge values and mapping. |
packages/gamut/src/Drawer/Drawer.stories.tsx |
Uses start-aligned drawer content. |
packages/gamut/src/Disclosure/types.ts |
Migrates button-placement contract and docs. |
packages/gamut/src/Disclosure/helpers.tsx |
Migrates helper placement types. |
packages/gamut/src/Disclosure/elements.tsx |
Uses logical button placement variants. |
packages/gamut/src/Disclosure/DisclosureBody.tsx |
Defaults button placement to end. |
packages/gamut/src/DatePicker/DatePicker.tsx |
Migrates calendar popover placement. |
packages/gamut/src/DatePicker/DatePicker.stories.tsx |
Migrates composed calendar placement. |
packages/gamut/src/DataList/types.ts |
Changes column justification values. |
packages/gamut/src/DataList/testUtils.tsx |
Migrates fixture alignments. |
packages/gamut/src/DataList/Tables/Rows/TableRow.tsx |
Defaults cell text alignment to start. |
packages/gamut/src/DataList/DataTable.stories.tsx |
Migrates column and menu placements. |
packages/gamut/src/DataList/Controls/SortControl.tsx |
Aligns sort text to start. |
packages/gamut/src/DataList/Controls/FilterControl.tsx |
Migrates justification and filter placement. |
packages/gamut/src/ConnectedForm/ConnectedFormGroup.stories.tsx |
Migrates InfoTip placement. |
packages/gamut/src/Coachmark/Coachmark.stories.tsx |
Migrates beak and alignment controls. |
packages/gamut/src/Button/shared/types.ts |
Changes icon-position values. |
packages/gamut/src/Button/shared/InlineIconButton.tsx |
Defaults icon position to start. |
packages/gamut/src/Button/IconButton.stories.tsx |
Migrates tooltip alignment controls. |
packages/gamut/src/Button/ButtonExamples.stories.tsx |
Demonstrates end-positioned icons. |
packages/gamut/src/BarChart/BarChart.stories.tsx |
Aligns the external title to end. |
packages/gamut/src/Badge/index.tsx |
Uses start-positioned icons. |
packages/gamut/src/Anchor/index.tsx |
Defaults icon position to start. |
packages/gamut/src/Anchor/Anchor.stories.tsx |
Migrates icon-placement examples. |
packages/gamut/src/Alert/Alert.stories.tsx |
Migrates close-button tooltip placement. |
packages/gamut-docs/src/content/docs/guides/writing-guidance.md |
Extends logical naming guidance to values. |
packages/gamut-docs/src/content/docs/concepts/naming-conventions-rationale.md |
Explains logical value naming and RTL behavior. |
packages/gamut-docs/src/content/docs/components/overlays/popover.mdx |
Documents logical alignment and beak values. |
packages/gamut-docs/src/content/docs/components/overlays/popover-container.mdx |
Documents logical placement options. |
packages/gamut-docs/src/content/docs/components/navigation/anchor.mdx |
Documents logical icon positioning. |
packages/gamut-docs/src/content/docs/components/inputs-and-forms/select-dropdown.mdx |
Documents end-aligned menus. |
packages/gamut-docs/src/content/docs/components/inputs-and-forms/GridForm/reference.mdx |
Updates submit-position reference. |
packages/gamut-docs/src/content/docs/components/inputs-and-forms/GridForm/patterns.mdx |
Updates section-layout guidance. |
packages/gamut-docs/src/content/docs/components/feedback/Tips/tooltip.mdx |
Documents logical side placements. |
packages/gamut-docs/src/content/docs/components/feedback/Tips/previewtip.mdx |
Updates corner alignment reference. |
packages/gamut-docs/src/content/docs/components/feedback/Tips/infotip.mdx |
Updates corner alignment reference. |
packages/gamut-docs/src/content/docs/components/feedback/Tips/index.mdx |
Updates shared alignment overview. |
packages/gamut-docs/src/content/docs/components/data-display/list-and-tables/List/list-col.mdx |
Documents end justification. |
packages/gamut-docs/src/content/docs/components/containers/drawer.mdx |
Documents logical content-edge values. |
packages/gamut-docs/src/content/docs/components/containers/disclosure.mdx |
Documents logical button placement. |
packages/gamut-docs/src/content/docs/components/actions/toggle.mdx |
Links to renamed label-side stories. |
packages/gamut-agent-tools/skills/gamut-select-dropdown/SKILL.md |
Updates menu-alignment reference. |
packages/gamut-agent-tools/skills/gamut-menu/SKILL.md |
Migrates placement examples. |
packages/gamut-agent-tools/skills/gamut-datatable/SKILL.md |
Migrates justification and popover guidance. |
packages/gamut-agent-tools/skills/gamut-buttons/SKILL.md |
Updates icon-position reference. |
packages/code-connect/Organisms/GridForm.figma.tsx |
Adds migration TODO comments only. |
packages/code-connect/Molecules/Tips/ToolTip.figma.tsx |
Adds an alignment migration TODO only. |
packages/code-connect/Molecules/Tips/PreviewTip.figma.tsx |
Adds an alignment migration TODO only. |
packages/code-connect/Molecules/Tips/InfoTip.figma.tsx |
Adds an alignment migration TODO only. |
packages/code-connect/Molecules/Popover.figma.tsx |
Adds an alignment migration TODO only. |
packages/code-connect/Molecules/Flyout.figma.tsx |
Adds an opening-edge migration TODO only. |
packages/code-connect/Molecules/Disclosure.figma.tsx |
Adds a button-placement migration TODO only. |
packages/code-connect/Molecules/Coachmark.figma.tsx |
Adds a beak migration TODO only. |
packages/code-connect/Atoms/FormInputs/Radio.figma.tsx |
Adds an InfoTip migration TODO only. |
packages/code-connect/Atoms/FormGroup.figma.tsx |
Adds an InfoTip migration TODO only. |
packages/code-connect/Atoms/Drawer.figma.tsx |
Adds a content-edge migration TODO only. |
packages/code-connect/Atoms/Anchor.figma.tsx |
Adds an icon-position migration TODO only. |
packages/.storybook/components/Elements/ImageGallery.tsx |
Aligns image labels to start. |
packages/.storybook/argTypes/infotip.tsx |
Migrates InfoTip controls and default. |
packages/.storybook/argTypes/closeButtonProps.tsx |
Migrates tooltip alignment options. |
.changeset/spotty-lilies-shout.md |
Adds release notes for the prop migration. |
Review effort: Balanced
| options: ['bottom-start', 'bottom-end', 'top-start', 'top-end'], | ||
| table: { | ||
| defaultValue: { summary: 'top-right' }, | ||
| defaultValue: { summary: 'top-end' }, |
| options: ['start', 'end', 'center'], | ||
| table: { | ||
| type: { | ||
| summary: 'left | right | center', |
| options: ['start', 'end', 'center'], | ||
| table: { | ||
| type: { | ||
| summary: 'left | right | center', |
Resolve conflicts: keep the styleguide package deleted as on main, and use the branch's story versions for List, Popover, and PreviewTip, with left/right values updated to start/end. Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Overview
Directional prop values now use logical
start/endinstead of physicalleft/right, so they stay correct in right-to-left (RTL) layouts.There are no
left/rightaliases.Consuming apps will be migrated with a codemod in a separate branch.
Component props (
feat!)buttonPlacementalignContentContaineropenFrommenuAlignmentjustifylabelSideiconPositionon FillButton, StrokeButton, TextButton, Anchor, Tag, and Badgelayoutandsubmit.positionPopover, PopoverContainer, and Tips alignments (
feat!)alignandbeak(also Coachmarkbeak):start|end|centeralignment:top-start,top-end,bottom-start,bottom-end,top,bottom,start,endalignment(and ModaltipAlignment):top-start,top-end,bottom-start,bottom-end,start-center,end-center,top-center,bottom-centerPopoverContainer resolves logical alignments to physical ones with
resolvePhysicalAlignment, which replacesmirrorAlignment.Popover's
resolveHorizontalSideForRtlnow takesstart/endand returns a physical side.CSS keyword swaps (
fix)SelectDropdown option labels, DataList SortControl, the ProgressBar percent label, and a few stories and Storybook components now use
start/endfortext-alignandjustify-content.LTR rendering is unchanged.
Docs
The naming conventions rationale page explains why prop values use
start/end, and the writing guidance page links to it and covers prop values in its RTL rule.Stories, gamut-docs pages, and agent skills are updated to match.
Code Connect files keep
left/rightwith TODO comments until the Figma changes take effect.Not in this PR
ScaleChartHeadertextAlign, which needs itsleft: %/translateXmath made direction-aware first.backgroundPosition: 'right', which has no logical CSS keyword.shadowvaluespatternLeft/patternRight.BREAKING CHANGE:
leftandrightare no longer accepted in these prop values.Use
startin place ofleftandendin place ofright, e.g.top-leftbecomestop-startandright-centerbecomesend-center.PR Checklist
Testing Instructions
Check each of the following Storybook pages three ways:
main.start/endplacements mirror:startsits on the right andendsits on the left.Component props
Containers/Disclosure: the body button sits at the end by default and at the start when thebuttonPlacementcontrol is set tostart.Containers/Drawer: the content stays pinned to thealignContentContaineredge while the drawer animates.Overlays/Flyout: the flyout opens from the start edge by default.Inputs & forms/SelectDropdown: the menu lines up with the input's end edge in themenuAlignment: 'end'story, and option right labels align to the end.Data display/DataTableandData display/DataList:justify: 'end'columns align to the end, column filter menus open toward the inside of the table, and sort headers align to the start.Data display/List/List,Data display/List/ListCol, andData display/List/ListRow:justify="end"columns align to the end.Actions/Toggle: the label sits at the end by default and at the start withlabelSide: 'start'.Actions/Buttons/Button Examples,Actions/Buttons/FillButton,Actions/Buttons/StrokeButton, andActions/Buttons/TextButton: icons sit before the label by default and after it withiconPosition="end".Navigation/Anchor: sameiconPositioncheck as the buttons.Actions/TagandStatus/Badge: icons sit before the label.Inputs & forms/GridForm/Buttons,Inputs & forms/GridForm/Layout, andInputs & forms/GridForm/Usage: the submit button followssubmit.position, and section titles withlayout: 'start'take the start column.Popover, PopoverContainer, and Tips alignments
Overlays/Popover: check everyalign/beakstory, including Center Left, Center Right, the pattern stories, and the Rtl stories, and confirm the beak points at the target.Overlays/PopoverContainer: check each corner and single-side alignment, inline and portaled.Feedback/Coachmark: the beak sits on thebeakside.Feedback/Tips/ToolTip,Feedback/Tips/InfoTip, andFeedback/Tips/PreviewTip: check every alignment, both inline and floating, and confirm the beak points at the trigger.Actions/Menu/MenuandActions/Menu/MenuItem:end-centertooltips open beside the item.Actions/Buttons/IconButton: tooltips open on the selected side.Inputs & forms/DatePicker,Inputs & forms/Form/FormGroup,Feedback/Alert, andPatterns/FloatingMenu: popovers and tips open where they did before.CSS keyword swaps
Status/ProgressBar: the percent label aligns to the end.Data display/BarChart: the external title story aligns to the end.Docs
Concepts/Naming conventions rationaleandGuides/Writing guidance, and click the reading-direction rationale link to confirm it lands on the "Staying correct in both reading directions" section.PR Links and Envs