Skip to content

* proj: replace the deprecated circle class with rounded-full - #245

Merged
catouse merged 3 commits into
dev_optimize_css_libsfrom
dev_optimize_circle_class
Aug 31, 2026
Merged

* proj: replace the deprecated circle class with rounded-full#245
catouse merged 3 commits into
dev_optimize_css_libsfrom
dev_optimize_circle_class

Conversation

@Lwrless

@Lwrless Lwrless commented Aug 24, 2026

Copy link
Copy Markdown
Member

lib/utilities/src/borders/rounded.css:9 marks .circle deprecated in favour of
.rounded-full, aliasing both to -rounded-full. This sweeps the remaining call sites.

Stacked on #240. 126 of the sites live in lib/avatar-group/README.md and its docs
page, both rewritten by that PR, so the base is dev_optimize_css_libs rather than
dev_optimize. When #240 merges GitHub retargets this automatically — provided the
branch is deleted on merge
; otherwise retarget by hand.

Commits

  1. docs and dev pages — 190 replacements over 178 lines in 16 files.
  2. component output@zui/avatar and @zui/upload-imgs move to rounded-full.
  3. compatibility — those two keep emitting circle as well.

Commits 2 and 3 are kept separate because the middle state is the interesting one to
review: 2 alone is a breaking change for downstream CSS, and 3 is the reason this PR is
not one. Happy to squash them if you prefer a single commit.

No breaking change

Commit 2 on its own would break anyone whose CSS selects .circle on an avatar or on the
upload-imgs file-size badge — the only part of this branch with blast radius outside the
repo, hiding inside what otherwise reads as a docs sweep. Commit 3 emits both classes
instead, the ordinary way to retire a class in shipped output: existing consumer CSS keeps
matching, while the components stop making the deprecated name the only option.

The two DOM tests assert both names, so dropping either becomes a deliberate edit. When
the alias is finally removed from rounded.css, circle comes out of the two call sites
and the two assertions together.

@zui/search-box emits only rounded-full for its identical circle option
(search-box.tsx:188). That break already shipped; left alone rather than widening this PR.

Two things the original scan missed

The sweep was scoped from a scan of class / className attribute values, which found
177 sites. Two categories sit outside that shape and are included here:

  • Runtime class strings in two componentsavatar/src/component/avatar.tsx:58
    (finalClass.push('circle')) and upload-imgs/src/vanilla/upload-imgs.ts:122
    (.addClass('… circle …')) put the class into consumers' DOM, not just the docs.
  • data-type / type values in the messager docs. messager-item.tsx:44 feeds
    type straight into classes(), so data-type="primary circle" renders the class at
    runtime. Their button labels mirror the value and move with it.

Deliberately untouched

light-circle, progress-circle, the .circle selector in rounded.css itself, the
<circle> SVG elements in @zui/progress-circle, the circleColor / circleWidth /
circleBg props, and the circle option props of @zui/avatar, @zui/picker and
@zui/search-box. A loose s/circle/rounded-full/g corrupts all of these.

Removing the deprecated alias from rounded.css is out of scope — it is a public CSS
class and dropping it breaks downstream consumers. Sweep first, decide the alias later.

Verification

  • 0 remaining circle class tokens in docs under lib/; guard-token counts unchanged
    (light-circle 49, progress-circle 10, circleColor 12, circleWidth 13,
    circleBg 9, circleSize 5, <circle 2).
  • Every changed doc line differs only by the token — checked line-by-line, not by eye.
  • pnpm build emits byte-identical CSS for all seven artifacts.
  • The rendered avatar-group docs page has all 584 class attributes identical once
    circle and rounded-full are normalised to one token.
  • pnpm check green; pnpm docs:build green.

Note on line endings

Four .md files use CRLF (avatar/README.md, both avatar-group files,
input-control/docs/…/index.md). A first pass normalised them to LF and inflated the diff
to 838 lines; endings are preserved here, so the doc diff is 182 lines.

`lib/utilities/src/borders/rounded.css:9` marks `.circle` deprecated in favour
of `.rounded-full`, aliasing both to `-rounded-full`. This sweeps the call
sites in READMEs, docs pages and one `dev.ts`.

Both classes compile to the same declaration, so this is rendering-neutral by
construction.

## Scope

190 replacements over 178 lines in 16 files:

- 177 inside `class` / `className` attribute values, matched as whole class
  tokens. `light-circle`, `progress-circle`, the `.circle` selector in
  `rounded.css` itself and the `circle` option props of `@zui/avatar`,
  `@zui/picker` and `@zui/search-box` are deliberately untouched.
- 13 in three places an attribute-scoped scan does not reach:
  - `messager/README.md` `data-type="… circle"` and
    `messager/docs/…/index.md` `type: '… circle'`. `messager-item.tsx:44`
    feeds `type` straight into `classes()`, so these render the deprecated
    class at runtime. Their button labels mirror the value and move with it.
  - `button/docs/…/index.md:271`, prose naming the utility class.

Four `.md` files use CRLF (`avatar/README.md`, both `avatar-group` files,
`input-control/docs/…/index.md`); line endings are preserved, so every changed
line differs only by the token.

## Not covered here

`avatar/src/component/avatar.tsx:58` and
`upload-imgs/src/vanilla/upload-imgs.ts:122` also emit `circle`. Those change
shipped component output rather than documentation, so they are a separate
commit.
Two components still put the deprecated `.circle` class on the elements they
render, so it reaches consumers' DOM rather than only the docs:

- `avatar/src/component/avatar.tsx:58` — every `<Avatar circle>`.
- `upload-imgs/src/vanilla/upload-imgs.ts:122` — the file-size badge.

`@zui/search-box` already maps its identical `circle` option to
`rounded-full` (`search-box.tsx:188`), so this brings the other two in line
with the direction the repo had already taken.

The `circle` option itself is public API and is unchanged in all three; only
the class name it produces moves. `.circle` and `.rounded-full` are aliased in
`rounded.css:9-10`, and nothing in the repo selects `.circle` from CSS or
queries it from JS, so rendering is unaffected.

`tests/dom/avatar.test.tsx` asserted the emitted class in two places and moves
with it. Verified that `pnpm build` emits byte-identical CSS for all seven
artifacts before and after.
The previous commit swapped the class these two components emit. That is a
breaking change for anyone downstream whose CSS selects `.circle` on an avatar
or on the upload-imgs file-size badge — the one part of this branch with blast
radius outside the repo, and it was hiding inside what otherwise reads as a
documentation sweep.

Both classes are emitted instead, which is the ordinary way to retire a class
in shipped output: existing consumer CSS keeps matching, and the components no
longer make the deprecated name the only option.

`.circle` and `.rounded-full` are aliased in `rounded.css:9-10`, so emitting
both adds one class token and changes nothing about rendering.

The two DOM tests assert both names, so dropping either becomes a deliberate
edit rather than a silent one. When the alias is finally removed from
`rounded.css`, `circle` comes out of these two call sites and those two
assertions at the same time.

Note `@zui/search-box` emits only `rounded-full` for its identical `circle`
option (`search-box.tsx:188`). That break already shipped and is left alone
here rather than widening this branch.
@catouse
catouse marked this pull request as ready for review August 31, 2026 02:49
@catouse
catouse merged commit d8c0260 into dev_optimize_css_libs Aug 31, 2026
0 of 3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants