kayg/calternal

Watch

Fork 0

DOCS: add module and function notes and remove product names in packages/ui #901

New issue

Open

opened 2026-10-02 17:38:28 +00:00 by kayg · 3 comments

kayg commented

2026-10-02 17:38:28 +00:00

Owner

Evidence

At the #863 audit base, 19 files in packages/ui/src have no leading module comment. Examples: components/surfaceViewport.svelte.ts:1 and components/Disclosure.svelte:1.
A case-sensitive scan found 93 comment lines in 37 files that name common third-party products. Examples: floating.ts:15-16 names browser engines; :210 names Finder.
Non-obvious exports without a function comment include actions/resizableEdge.ts:55 (readPanelWidth) and :100 (resizableEdge), which persist and clamp a user's panel width and expose keyboard resizing.

Owner rule

Comments are documentation. Each module and each non-obvious function needs a short, current comment. Source comments must not name third-party products.

Expected behaviour

Add module comments to the identified modules. Explain width persistence, clamping, collapse/reset, and keyboard invariants on the resizable-edge API. Replace product names with platform-neutral behavior or the applicable web standard. Preserve code behavior. The motion contradiction in calendar/GridColumn.svelte:974 is already tracked in #611.

Test idea

Run a source scan for module/function comments and third-party names. Review the resizable panel behavior against its existing tests without changing their expectations.

## Evidence At the #863 audit base, 19 files in `packages/ui/src` have no leading module comment. Examples: `components/surfaceViewport.svelte.ts:1` and `components/Disclosure.svelte:1`. A case-sensitive scan found 93 comment lines in 37 files that name common third-party products. Examples: `floating.ts:15-16` names browser engines; `:210` names Finder. Non-obvious exports without a function comment include `actions/resizableEdge.ts:55` (`readPanelWidth`) and `:100` (`resizableEdge`), which persist and clamp a user's panel width and expose keyboard resizing. ## Owner rule Comments are documentation. Each module and each non-obvious function needs a short, current comment. Source comments must not name third-party products. ## Expected behaviour Add module comments to the identified modules. Explain width persistence, clamping, collapse/reset, and keyboard invariants on the resizable-edge API. Replace product names with platform-neutral behavior or the applicable web standard. Preserve code behavior. The motion contradiction in `calendar/GridColumn.svelte:974` is already tracked in #611. ## Test idea Run a source scan for module/function comments and third-party names. Review the resizable panel behavior against its existing tests without changing their expectations.

kayg referenced this issue

2026-10-02 17:44:36 +00:00

Audit: module docs and stale comments (comments are docs) #863

kayg commented

2026-10-02 17:55:08 +00:00

Author

Owner

Web comment fix committed as 160c7596bce40ac21921a70d4febf9fbdc74a89d for #901. Added 19 file-boundary module comments, documented saved-width fallback/clamping and resize commit/collapse/reset invariants, and replaced product comparisons with behavior descriptions. Corrected current app stylesheet references. The comment in GridColumn now states the current focus rule and points to #611; its CSS behavior is unchanged. Executable source and directives are unchanged in all 62 files (comment-stripped source comparison).

Prettier check output (exit 1):

Checking formatting...
[warn] packages/ui/src/actions/portal.ts
[warn] packages/ui/src/actions/resizableEdge.ts
[warn] packages/ui/src/components/Card.svelte
[warn] packages/ui/src/components/Checkbox.svelte
[warn] packages/ui/src/components/ChromeActions.svelte
[warn] packages/ui/src/components/DateStrip.svelte
[warn] packages/ui/src/components/Disclosure.svelte
[warn] packages/ui/src/components/FloatingSidebar.svelte
[warn] packages/ui/src/components/Inspector.svelte
[warn] packages/ui/src/components/Kbd.svelte
[warn] packages/ui/src/components/LinkedHeading.svelte
[warn] packages/ui/src/components/ModeHeader.svelte
[warn] packages/ui/src/components/OverlaySurface.svelte
[warn] packages/ui/src/components/Pill.svelte
[warn] packages/ui/src/components/PillGroup.svelte
[warn] packages/ui/src/components/PrimaryPill.svelte
[warn] packages/ui/src/components/ProgressiveBlur.svelte
[warn] packages/ui/src/components/SegmentedControl.svelte
[warn] packages/ui/src/components/Select.svelte
[warn] packages/ui/src/components/SelectionBar.svelte
[warn] packages/ui/src/components/SettingRow.svelte
[warn] packages/ui/src/components/SidebarIcon.svelte
[warn] packages/ui/src/components/SidebarSectionHeader.svelte
[warn] packages/ui/src/components/StatusPill.svelte
[warn] packages/ui/src/components/ThemePicker.svelte
[warn] packages/ui/src/components/Toggle.svelte
[warn] packages/ui/src/components/WeekBlob.svelte
[warn] packages/ui/src/components/calendar/AgendaList.svelte
[warn] packages/ui/src/components/calendar/AttachmentDeck.svelte
[warn] packages/ui/src/components/calendar/GridColumn.svelte
[warn] packages/ui/src/components/calendar/MiniMonth.svelte
[warn] packages/ui/src/components/calendar/MonthGrid.svelte
[warn] packages/ui/src/components/calendar/TimeGrid.svelte
[warn] packages/ui/src/components/calendar/layout.ts
[warn] packages/ui/src/components/calendar/model.ts
[warn] packages/ui/src/components/calendar/snap.ts
[warn] packages/ui/src/components/calendar/window.ts
[warn] packages/ui/src/components/calendar/zoom.ts
[warn] packages/ui/src/components/composer/DraftStack.svelte
[warn] packages/ui/src/components/files/FileCollection.svelte
[warn] packages/ui/src/components/files/FileSelectionCheckbox.svelte
[warn] packages/ui/src/components/menu/FloatingSurface.svelte
[warn] packages/ui/src/components/menu/Menu.svelte
[warn] packages/ui/src/components/menu/MenuSeparator.svelte
[warn] packages/ui/src/components/menu/types.ts
[warn] packages/ui/src/components/modeIsland.css
[warn] packages/ui/src/components/notes/NoteMentionsCard.svelte
[warn] packages/ui/src/components/notes/NoteProperties.svelte
[warn] packages/ui/src/components/surfaceViewport.svelte.ts
[warn] packages/ui/src/components/viewer/ImageView.svelte
[warn] packages/ui/src/components/viewer/LiveMotion.svelte
[warn] packages/ui/src/components/viewer/PdfView.svelte
[warn] packages/ui/src/components/viewer/QuickLook.svelte
[warn] packages/ui/src/components/viewer/TextView.svelte
[warn] packages/ui/src/components/viewer/VideoView.svelte
[warn] packages/ui/src/floating.ts
[warn] packages/ui/src/gestures.ts
[warn] packages/ui/src/motion.ts
[warn] packages/ui/src/time.ts
[warn] packages/ui/src/tokens.css
[warn] packages/ui/src/weekStart.ts
[warn] Code style issues found in 61 files. Run Prettier with --write to fix.

Existing code formatting will not be changed in this comment-only job. Final combined checks follow after the required origin/dev update. No tests or builds run.

Web comment fix committed as `160c7596bce40ac21921a70d4febf9fbdc74a89d` for #901. Added 19 file-boundary module comments, documented saved-width fallback/clamping and resize commit/collapse/reset invariants, and replaced product comparisons with behavior descriptions. Corrected current app stylesheet references. The comment in GridColumn now states the current focus rule and points to #611; its CSS behavior is unchanged. Executable source and directives are unchanged in all 62 files (comment-stripped source comparison). Prettier check output (exit 1): ```text Checking formatting... [warn] packages/ui/src/actions/portal.ts [warn] packages/ui/src/actions/resizableEdge.ts [warn] packages/ui/src/components/Card.svelte [warn] packages/ui/src/components/Checkbox.svelte [warn] packages/ui/src/components/ChromeActions.svelte [warn] packages/ui/src/components/DateStrip.svelte [warn] packages/ui/src/components/Disclosure.svelte [warn] packages/ui/src/components/FloatingSidebar.svelte [warn] packages/ui/src/components/Inspector.svelte [warn] packages/ui/src/components/Kbd.svelte [warn] packages/ui/src/components/LinkedHeading.svelte [warn] packages/ui/src/components/ModeHeader.svelte [warn] packages/ui/src/components/OverlaySurface.svelte [warn] packages/ui/src/components/Pill.svelte [warn] packages/ui/src/components/PillGroup.svelte [warn] packages/ui/src/components/PrimaryPill.svelte [warn] packages/ui/src/components/ProgressiveBlur.svelte [warn] packages/ui/src/components/SegmentedControl.svelte [warn] packages/ui/src/components/Select.svelte [warn] packages/ui/src/components/SelectionBar.svelte [warn] packages/ui/src/components/SettingRow.svelte [warn] packages/ui/src/components/SidebarIcon.svelte [warn] packages/ui/src/components/SidebarSectionHeader.svelte [warn] packages/ui/src/components/StatusPill.svelte [warn] packages/ui/src/components/ThemePicker.svelte [warn] packages/ui/src/components/Toggle.svelte [warn] packages/ui/src/components/WeekBlob.svelte [warn] packages/ui/src/components/calendar/AgendaList.svelte [warn] packages/ui/src/components/calendar/AttachmentDeck.svelte [warn] packages/ui/src/components/calendar/GridColumn.svelte [warn] packages/ui/src/components/calendar/MiniMonth.svelte [warn] packages/ui/src/components/calendar/MonthGrid.svelte [warn] packages/ui/src/components/calendar/TimeGrid.svelte [warn] packages/ui/src/components/calendar/layout.ts [warn] packages/ui/src/components/calendar/model.ts [warn] packages/ui/src/components/calendar/snap.ts [warn] packages/ui/src/components/calendar/window.ts [warn] packages/ui/src/components/calendar/zoom.ts [warn] packages/ui/src/components/composer/DraftStack.svelte [warn] packages/ui/src/components/files/FileCollection.svelte [warn] packages/ui/src/components/files/FileSelectionCheckbox.svelte [warn] packages/ui/src/components/menu/FloatingSurface.svelte [warn] packages/ui/src/components/menu/Menu.svelte [warn] packages/ui/src/components/menu/MenuSeparator.svelte [warn] packages/ui/src/components/menu/types.ts [warn] packages/ui/src/components/modeIsland.css [warn] packages/ui/src/components/notes/NoteMentionsCard.svelte [warn] packages/ui/src/components/notes/NoteProperties.svelte [warn] packages/ui/src/components/surfaceViewport.svelte.ts [warn] packages/ui/src/components/viewer/ImageView.svelte [warn] packages/ui/src/components/viewer/LiveMotion.svelte [warn] packages/ui/src/components/viewer/PdfView.svelte [warn] packages/ui/src/components/viewer/QuickLook.svelte [warn] packages/ui/src/components/viewer/TextView.svelte [warn] packages/ui/src/components/viewer/VideoView.svelte [warn] packages/ui/src/floating.ts [warn] packages/ui/src/gestures.ts [warn] packages/ui/src/motion.ts [warn] packages/ui/src/time.ts [warn] packages/ui/src/tokens.css [warn] packages/ui/src/weekStart.ts [warn] Code style issues found in 61 files. Run Prettier with --write to fix. ``` Existing code formatting will not be changed in this comment-only job. Final combined checks follow after the required origin/dev update. No tests or builds run.

kayg referenced this issue from a commit

2026-10-02 17:56:19 +00:00

docs(ui): explain module boundaries and resize invariants (#901)

kayg commented

2026-10-02 18:09:31 +00:00

Author

Owner

Final comment-only commit for #901: 68d99959878cd4245edeb06e25fadfb1fcbc1ceb (supersedes the intermediate SHA above). The branch also contains the requested origin/dev update; final head a82305864d94a3194015404b6deddbb366ab55b1.

Source comparison: executable source and test directives are unchanged across all 409 files. All 246 audit-listed modules have leading comments.

Final gates: cargo fmt --check exited 0 with no stdout or stderr. The combined bunx prettier --check exited 1:

[warn] Code style issues found in 405 files. Run Prettier with --write to fix.

The same 405 files fail the same formatter on origin/dev; there are zero new formatting failures. No code formatting changed. Full gate output and file inventory are in the final #863 report. No builds or runtime tests run, as required by this job. This issue remains open.

Final comment-only commit for #901: `68d99959878cd4245edeb06e25fadfb1fcbc1ceb` (supersedes the intermediate SHA above). The branch also contains the requested `origin/dev` update; final head `a82305864d94a3194015404b6deddbb366ab55b1`. Source comparison: executable source and test directives are unchanged across all 409 files. All 246 audit-listed modules have leading comments. Final gates: `cargo fmt --check` exited 0 with no stdout or stderr. The combined `bunx prettier --check` exited 1: ```text [warn] Code style issues found in 405 files. Run Prettier with --write to fix. ``` The same 405 files fail the same formatter on `origin/dev`; there are zero new formatting failures. No code formatting changed. Full gate output and file inventory are in the final #863 report. No builds or runtime tests run, as required by this job. This issue remains open.

kayg referenced this issue

2026-10-02 18:09:58 +00:00

Audit: module docs and stale comments (comments are docs) #863

kayg referenced this issue from a commit

2026-10-02 18:10:51 +00:00

docs(ui): explain module boundaries and resize invariants (#901)

kayg commented

2026-10-03 00:35:37 +00:00

Author

Owner

Repair on job/docsfix-web (not pushed): bf5d2643f docs(web): restore platform, browser and library names in comments.

Clarified rule (owner, 2026-10-02): do not name competing apps (other notes, calendar, mail or photo apps) in UI, code or comments. Platform, OS, browser, protocol, client and library names that state technical facts stay.

The name scrub replaced facts with garbled stand-ins in about 750 comment lines: "iOS 26.5" became "touch-platform.5", "Safari 15+" became "the browser 15+", "than the" became "tha". This commit restores:

every platform, browser and client name (iOS, iPadOS, macOS, Safari, WebKit, Chromium, Chrome, Firefox, Finder, Apple Calendar, iPhone, iPad, Android, Windows, Linux);
library names (ProseMirror, TipTap, StarterKit, Yjs, Yrs, jsdom, Sonner, Bklit, Torph, lowlight, highlight.js, pdf.js, hls.js, Svelte, React, Lucide, Playwright);
the focus-ring research references (.superpowers/sdd/focus-ring-research.md, research §0/§1/§5b), whatwg/html#8087 with engine versions, WebKit bug 296492 and the iOS gesture research note;
Claude, Codex and Unsplash in comments, and iCloud, Fastmail and Nextcloud as CalDAV servers in the Calendars header.

Kept: the new module headers, the app.css → calternal-app.css path fixes, the #611 motion notes and the retired-task cleanup in slash.test.ts. Competing notes, photo and budget apps (Obsidian, Craft, Notion, Fantastical, Immich, Google Photos, Apple Photos, Apple Notes, YNAB) stay unnamed. Their stand-ins now read as plain English (for example "extended-Markdown pipe syntax", "envelope-budget", "common note editors").

Repair on `job/docsfix-web` (not pushed): `bf5d2643f` docs(web): restore platform, browser and library names in comments. Clarified rule (owner, 2026-10-02): do not name competing apps (other notes, calendar, mail or photo apps) in UI, code or comments. Platform, OS, browser, protocol, client and library names that state technical facts stay. The name scrub replaced facts with garbled stand-ins in about 750 comment lines: "iOS 26.5" became "touch-platform.5", "Safari 15+" became "the browser 15+", "than the" became "tha". This commit restores: - every platform, browser and client name (iOS, iPadOS, macOS, Safari, WebKit, Chromium, Chrome, Firefox, Finder, Apple Calendar, iPhone, iPad, Android, Windows, Linux); - library names (ProseMirror, TipTap, StarterKit, Yjs, Yrs, jsdom, Sonner, Bklit, Torph, lowlight, highlight.js, pdf.js, hls.js, Svelte, React, Lucide, Playwright); - the focus-ring research references (`.superpowers/sdd/focus-ring-research.md`, research §0/§1/§5b), whatwg/html#8087 with engine versions, WebKit bug 296492 and the iOS gesture research note; - Claude, Codex and Unsplash in comments, and iCloud, Fastmail and Nextcloud as CalDAV servers in the Calendars header. Kept: the new module headers, the `app.css` → `calternal-app.css` path fixes, the #611 motion notes and the retired-task cleanup in `slash.test.ts`. Competing notes, photo and budget apps (Obsidian, Craft, Notion, Fantastical, Immich, Google Photos, Apple Photos, Apple Notes, YNAB) stay unnamed. Their stand-ins now read as plain English (for example "extended-Markdown pipe syntax", "envelope-budget", "common note editors"). Check: `git diff origin/dev...HEAD | grep '^-' | grep -E 'iOS|macOS|Safari|WebKit|Chrom|Firefox|Apple|Finder|Thunderbird|Android|Windows'` now lists only moved or rewrapped lines and the competing-app lines. Comments only. Prettier is not set up for Svelte in this repo, so I did not run it.

No labels

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

kayg/calternal#901

No description provided.

Rows
Columns