mirror of
https://github.com/twbs/bootstrap.git
synced 2026-11-16 06:58:43 +00:00
* fix(combobox): support native form values and events Multiple selections now submit one field per value. Commas stay in the value, and an empty multiple selection submits no entries. Reuse an explicit hidden input without removing application-owned fields. Keep a stable field for input and change listeners. Sync fields before notifications, restore initial selections on reset, and follow disabled state and form ownership. Document the update and disposal contracts. Forward Menu lifecycle events after its transitions. Keep native search editing keys and cover the sticky search padding with logical CSS. * feat(combobox): combine editable selection and chip entry Search and select values from one editable field. Multiple selections render as removable chips, and explicit free entry supports tags. Keep query text separate from committed values and preserve native form data. Use the existing Menu for positioning and lifecycle. Keep focus in the editor while suggestions are highlighted. Preserve chip nodes, caret positions, reset behavior, and input-method text during reconciliation. Retire the separate Chips plugin and chip-input control. Keep static chip styles and button-triggered Combobox markup. Document the alpha 2 markup, token, method, and event migration. * fix(combobox): match chip fields to the default input height Multiple values should fit the same row height as a normal input. Use shared input spacing and typography, with smaller contextual chips. Let the field grow when its values wrap. Replace the text dismiss glyph with the SVG from the chip documentation. Keep the named removal button and existing chip interaction behavior. * fix(combobox): separate chip icon size from its hit area Render the dismiss icon at 12px inside a 24px removal button. Move chips closer to the field's inline start while keeping normal text padding for an empty editor. Use logical spacing so the inset follows RTL. * fix(combobox): tighten chip dismiss spacing Use negative inline margins to bring the dismiss button closer to the label and chip edge. Keep its 24px hit area and 12px SVG artwork. * fix(combobox): derive chip corners from the field radius Use a nested chip radius based on the wrapping field's radius, border, and inset. Clamp the result at zero so square fields keep square chips. * fix(combobox): balance chip insets within the field Match the field's inline padding to its vertical padding when chips are present. Derive chip corners from that inset and pull the dismiss button's end margin in another 2px without reducing its hit area. * fix(combobox): soften chip corners within balanced fields Use half the field radius for chips so equal input padding does not leave their corners nearly square. Keep square fields square. * fix(combobox): restore chip selection and keyboard behavior Highlight chips with the filled active state when users navigate or select them. Restore modifier clicks, anchored ranges, select-all, and deletion of highlighted chips. Keep native query editing and RTL keys. Keep chip highlights separate from committed values. Report UI selection through select.bs.combobox and restore the chip selection methods on Combobox. Bulk removal honors each cancellation and emits one value change before recovering focus. Document the restored interaction and alpha migration. Cover range anchors, duplicate values, disabled chips, reset, and disposal. * fix(combobox): select chips on every focus path Tabbing to a chip's remove button or focusing a chip directly should show its primary selected state. Apply that highlight without changing committed values, and dismiss the suggestion popup. Guard focus controlled by range navigation and modifier clicks so it does not collapse or undo the user's chip selection. * fix(combobox): suppress inner chip focus outlines Keep the filled selected chip and the wrapping field's focus ring as focus indicators. Suppress the nested outlines on chips and their remove buttons during keyboard navigation. * fix(combobox): guard form and editor edge cases Selection callbacks can change or dispose the component before an outer operation completes. Stop stale selection and focus work after those callbacks, and keep pending popup sizing from changing disposed markup. Handle native composition events through the shared event system. Keep unfinished input out of blur commits, reconcile completed composition, and preserve focus after the editor loses it. Let the IME handle its keys in both Combobox and Menu. Follow external reset forms without a backing field, omit disabled single options, and clear references to removed or disabled suggestions. Add regressions and clarify the synchronous form update requirement. * docs(chips): move standalone chips to Components Chips can stand alone or appear within a form component. Place their docs in Components and describe that wider use. Keep the old Forms URL as a redirect, and update navigation and cross-links. * fix(chips): limit hover feedback to interactive chips Static chips change color and show a pointer cursor on hover, even when they have no action. Keep static chips neutral and apply hover feedback to links, buttons, and Combobox chips. A dismiss button keeps its own hover state without changing the whole chip. Add interactive examples and correct the documented CSS layer. Allow for the extra selectors in the unminified CSS bundle budget. * docs(combobox): lead with editable examples Show search and selection in the input from the first example. Use inputs for the shared examples and group the button variants together. Use the editable markup in the form and setup guidance too. * docs(combobox): restore the overview feature list Describe editable inputs and button toggles in the original overview. Include chips, free entry, form submission, and selection events. * docs(combobox): preserve example indentation Match the form field examples by adding the source indentation that MDX strips. Record the convention in the docs guidance. * fix(combobox): focus search directly when opening Clicking a searchable combobox moved focus to the trigger before the opening animation moved it to search. Focus search as soon as the menu opens. Keep the trigger in the tab order and return focus to it on Escape. * docs(combobox): style the Language example label * ci(combobox): fix bundle budgets and spelling Round the three JavaScript bundle limits up to the next quarter kilobyte to account for the search focus changes. Reword the docs indentation rule so it passes the spelling check. * fix(combobox): preserve resets and expose selection state A canceled second reset could discard a completed reset. Keep each pending reset until its own callback runs. Give button-mode options listbox roles, handle Escape on the toggle, and restore chip focus rings. Keep long values inside the field and use shared state tokens. * fix(combobox): fit chips to the shared control size Compact controls were 30px tall, but their fixed-height chips made the multiple-selection field 34px tall. Derive chip and dismiss-button heights from the space left by the control padding and borders. Check compact, default, and spacious controls in the browser. * docs(combobox): redirect chip input readers to the merged component The former chip input page now points to Combobox. Explain the consolidation at the top of that page and link the migration steps for existing chip inputs. * chore(combobox): account for the current main bundle size The rebased build includes the merged Range and hash-link fixes. Raise the three affected limits to the next standard budget step.
7.9 KiB
7.9 KiB
AGENTS.md
Guidance for AI coding agents working in this repository. Tool-agnostic; CLAUDE.md points here.
Bootstrap v6.0.0-alpha.1 — CSS/JS framework.
Sass source in scss/, TypeScript source in js/src/, docs site in site/ (Astro 5 + MDX).
Quick commands
npm start— dev server (watch + Astro on port 9001)npm run dist— full CSS + JS buildnpm run css— compile, prefix, minify CSSnpm run js— compile + minify JSnpm run css-lint/npm run js-lint— lintnpm run docs-build— build docs sitenpm test— full test suite (lint + dist + tests + docs)
Writing style
Use ASD-STE100 Simplified Technical English for all prose: replies to the user, docs, code comments, commit messages, and PR text.
- Write short sentences. Use approximately 20 words or fewer.
- Give one instruction per sentence.
- Use the active voice. Name the actor.
- Use simple verbs. Do not use a complex verb when a simple one works.
- Use one term for one thing. Keep terms the same across the project.
- Keep paragraphs short. Cover one topic per paragraph.
Reply length
Be extremely brief. Report the result, not the journey.
- Target 75 words or fewer. Hard cap 150 words, and only for a genuinely multi-part answer.
- Answer in the first sentence. Then stop.
- Give one supporting fact per claim, at most. Cut the rest.
- Do not narrate your process, tool calls, or verification steps. Report a check only when it failed or changed the outcome.
- Do not restate the work you just did. The user reads the diff, the commit, and the PR.
- State a finding once. Never repeat it in a summary or closing line.
- No headings. No tables. Use a list of 5 items or fewer only when the answer is a real list.
- Cut praise, apologies, hedging, and filler such as "great question" or "worth noting".
- Do not explain what you did not do, or list caveats the user did not ask about.
- Do not offer next steps unless the user asks or the work is blocked.
- Expand only when the user asks for detail, or asks you to teach.
Teaching
Act as a teacher for JavaScript, TypeScript, React, and all JavaScript-family topics.
- When the work hits a new problem, concept, or language feature, stop and explain it.
- Keep each explanation short and plain. Define jargon on first use.
- Use a small code example when it makes the idea clear.
- Assume strong HTML/CSS knowledge. Do not assume deep JS internals knowledge.
SCSS conventions
- Variable naming:
$component-state-property-size(e.g.,$nav-link-disabled-color) - Module system:
@use/@forwardonly — never@import - Token system: component tokens are SCSS maps of CSS custom properties, merged via
defaults(), output via@include tokens($map)on the component root selector - Disallowed: raw
border-radius/transitionproperties (use mixins),lighten()/darken(),border: none/outline: none - Order:
@use→@forward→$variables→--custom-properties→ declarations → rules - Variables use
!default(except locals) - CSS layers:
colors, config, root, reboot, layout, content, forms, components, custom, helpers, utilities - Logical properties: prefer
padding-inline-startoverpadding-left, etc. - Modern CSS:
color-mix(),light-dark(), range media queries (@media (width >= 1024px)) - Doc markers:
// scss-docs-start name/// scss-docs-end namefor docs extraction
JavaScript/TypeScript conventions
- Source is TypeScript (
js/src/**/*.ts, entryjs/src/index.ts); ESM-only, no semicolons, 2-space indent - Imports use
.jsextensions (standard TS ESM style); Rolldown resolves them to.tsviaresolve.extensionAlias, Vitest via thetsResolveplugin injs/tests/vitest.config.mts - Dist builds use Rolldown (
build/rolldown.config.mjs,build/build-plugins.mjs) with built-in TS transforms;build/browser-targets.mjsderives the browser floors from.browserslistrcat build time, so there is nothing to keep in sync. Rollup and Babel are gone from the repo — Vitest transforms the specs itself - Strict tsconfig with
verbatimModuleSyntax+erasableSyntaxOnly;tsconly type-checks and emits.d.ts(npm run js-typecheck,npm run js-emit-types) - Components extend
BaseComponent(which extendsConfig); per-component configtype XxxConfigtyped offDefault, refined on the class viaprotected declare _config: XxxConfig - Instance fields use
declare(no runtime emit); constructorelementparam stays optional to keeptypeof Componentassignable totypeof BaseComponent - Every
_-prefixed instance member isprotected(neverprivate, so subclasses keep access); public API methods and statics stay public. This keeps the internals out of the published.d.tssurface - Constants:
NAME,DATA_KEY,EVENT_KEY,VERSION - DOM utilities via
dom/event-handler.ts,dom/selector-engine.ts,dom/manipulator.ts - Floating UI for positioning (dropdown, tooltip, popover)
- Tests: Vitest browser mode (real Chromium via Playwright), config in
js/tests/vitest.config.mts, specs injs/tests/unit/*.spec.js(plain JS, bundled against the TS sources).js/tests/vitest-setup.jsmaps the Jasmine API the specs are written against onto Vitest — notespyOnstubs by default, unlikevi.spyOn. Async specs return a promise; Vitest 4 droppeddone. Coverage is Istanbul over all ofjs/src, thresholds 90/88/90/90 - Type-level API tests in
js/tests/types/—api.tschecks the source (npm run js-typecheck),consumer.tschecks the shippedjs/dist/*.d.tsthrough the packageexportsmap (npm run js-typecheck-dist, after the build). Keep the two in sync
Docs conventions
- Astro 5 + MDX in
site/src/content/docs/ - Frontmatter schema:
title(required),description(required),toc,aliases,added,mdn,reference, etc. - Shortcodes:
Example,Callout,Code,Details - For multiline
<Example code={...}>template literals that start on the same line as the shortcode, add two extra spaces to each following line of code. Top-level markup starts with two spaces in the source, and its children start with four. The rendered snippet removes the extra level. Followsite/src/content/docs/forms/field.mdxand check the rendered code before committing. - Internal links:
[[docsref:/path/]] - JS component "Dependencies" tables are auto-generated — add a
### Dependenciesheading with<JsDependencies component="<js-src-basename>" />(before### Options) on any doc for ajs/src/*.tscomponent. The table is derived at build time by walking the component's import graph insite/src/libs/js-dependencies.ts; never hand-write the file list. When a new source file or third-party package enters the graph, add its human-readable label toFILE_DESCRIPTIONS/PACKAGE_DESCRIPTIONSin that lib (the build throws if a label is missing).
Formatting
- 2 spaces, UTF-8, LF line endings, trim trailing whitespace, final newline
- Preserve smart punctuation (curly apostrophes U+2019, curly quotes) — never replace with ASCII equivalents
- Use
StrReplacefor targeted edits; avoid full-file rewrites on MDX files to protect typography
Workflow
- Validate after changes:
npm run css-lint,npm run js-lint,npm run dist,npm run docs-build - Keep config files in sync:
config.yml,site/src/libs/config.ts(Zod schema),build/rolldown.config.mjs,build/generate-sri.mjs,package.json - For rebases/conflicts: favor base branch structure, layer feature changes on top
Commits & PRs
- Commit messages: direct, succinct prose explaining why the change was made.
- PR descriptions: direct bulleted lists, minimal fluff — one bullet per notable change.
- Reference related issues/PRs explicitly with
Fixes #{issue},Closes #{issue}, orSupersedes #{pr}. - No "Test plan" section and no extra headings — just the bullets and the references.
Do not edit
Built output in dist/, _site/, js/dist/ — these are generated.