Link the packages to npm, not just to their source directories - #6
Merged
Conversation
The package table linked to the source directories, which is the one place a reader who wants to install something is not going. The names now point at npmjs and the source is a column beside them, and the header carries a version badge that reads from the registry rather than from a number in this file that would go stale on the next release. This is not the sidebar under Packages on GitHub. That lists GitHub Packages only, and GitHub Packages requires the scope to match the repository owner - `@softov/*` under softov/scena, which is why scena has one. `@textui/*` cannot be published there from softov/textui at all.
The README answered questions in the order they occurred to whoever wrote it. Someone arriving from npm or from a search got a code sample, then fifty-five lines about four different install permutations, and only at line 135 any hint that a documentation site exists. There is now a `Where to go` table directly under the example: npm to install, the docs site to learn, getting started to begin, the screenshots to look first, DEVELOPER.md to work on TextUI itself. Five rows, above everything else, because a reader who wants the docs should not have to scroll past an install matrix to find out there are any. Installing collapses to a table of the four cases and the two things that actually catch people - that widgets are registered rather than imported, and that `doctor` answers most "why does it render wrong". The walkthrough is in getting started, which is where it already was; the README was repeating it.
Owner
Author
|
Second commit addresses the real problem, which was not the links. The README answered questions in the order they occurred to whoever wrote it. Someone arriving from npm got a code sample, then fifty-five lines about four install permutations, and only at line 135 any hint that a documentation site exists. Where to goA table directly under the example, above everything else:
A reader who wants the docs should not have to scroll past an install matrix to discover there are any. Installing, collapsedFifty-five lines down to a four-row table plus the two things that actually catch people: that widgets are registered rather than imported, and that The walkthrough was duplicated — it already lives in getting started, which is where it belongs. The README was repeating it, which is how it got long enough to bury the documentation link. Anchors verified to resolve; docs:check clean. |
On npm, `@textui/kit` said it re-exports `@textui/core` and `@textui/terminal` and linked neither - and most sibling mentions across the nine READMEs were bare code spans that linked nowhere at all. Where a link did exist it pointed at the source directory on GitHub, which is not where a reader on a package page is trying to go. Every cross-reference is now a link, to npm for the six that are published and to the source for the ones that are not. Each README also ends with the family: six names, one line, the current package in bold rather than linked to itself. That is what makes the set navigable from any entry point, rather than only from the ones that happened to mention each other. The documentation link was `/getting-started/`, which 404s - Jekyll builds it as `getting-started.html`. Every URL in every package README was checked against the live site.
Owner
Author
|
Third commit: the package READMEs could not reach each other. On npm, Fixed
Connectivity verified as a matrix — all nine READMEs reach all six published packages, one footer each, no duplicates. One real bug caughtThe documentation link I was about to publish to npm was
(npmjs.com returns 403 to curl — Cloudflare, not a broken link. The registry API confirms all six.) Worth noting these only reach npm on the next publish, since README content ships inside the tarball. |
… asked Rewritten to your structure. It now serves the twenty-second reader (badges, one screenshot, two links out), the five-minute reader (kit, then widgets, then the CLI, each with a runnable example), and the reader who is already using it (the handle's members, the packages table, the docs index) - in that order, rather than mixing all three. Four things in the draft did not survive checking against the packages: - `<Badge>Online</Badge>` renders nothing. Badge takes `label`, not children; it is `<Badge label="Online" />`. - `const app = render(<App/>)` names the whole handle `app` when `app` is one of its four members. Destructured instead, like the example above it. - Requirements listed Node, Bun and TypeScript as three things you need. It is Node *or* Bun - both verified to run the published packages - and TypeScript is how the examples are written rather than something TextUI requires. - The illustration of a missing registration drew a framed panel. The frame is the component that failed to resolve, so there is no frame: the output is `<Card>` and nothing else. The claim the draft is built on does hold, and is checked: an imported component renders with no `registerBuiltins` anywhere, because the JSX factory carries the function on the node. The registry is for names that arrive as data, which is what the section now says.
The block was the output of a forgotten registration with nothing to say it was output, so it read as a stray fence. It is now framed as a console session and followed by a sentence naming what it is: the component's own name, drawn in red where the component should have been, which is the whole error - there is no stack trace to go and look for. A claim about a `diagnostics` variant went with it. The code does render `<Card?>` under that option, but it is an application option rather than a `renderToString` one, so the check for it did not actually exercise it - and an unverified detail is not worth the front page.
The six all release together, so a reader on any one of their npm pages should be able to see what version they are looking at without leaving it. Each published package README carries its own version and licence badge; the root table gains a version column so the whole set is legible at a glance. The three unpublished packages get none - there is no npm page for a badge to read. Downloads badges came out and went back: shields renders "package not found or too new" for a package published this morning, which would have shipped a grey error to six npm pages. Version and licence are the two that say something true today. Every badge URL was fetched and its rendered title checked - v0.1.0 six times, MIT six times, node >=22.
- Consolidated sentences for clarity in the packages and docs/
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The README's package table linked to
packages/facade,packages/coreand so on — the one place a reader who wants to install something is not going. Now that all six are on npm, the names point there.What changes
sourceas a column beside them so both destinations are one click.Verified the badge endpoints resolve against the real packages:
npm: v0.1.0,node: >=22,license: MIT.What this is not
This does not put anything in the Packages section of the GitHub sidebar, and that cannot be done for this repository.
That section lists GitHub Packages only, and GitHub Packages requires the scope to match the repository owner — the docs are explicit that the namespace is "the name of the user or organization account to which the package will be scoped".
softov/scenapublishes@softov/scena, so the scopes match and it gets a sidebar entry.softov/textuipublishes@textui/*, which is a scopesoftovdoes not own on GitHub, so that registry will reject it outright.The only way to get a real Packages entry would be to create a GitHub organization named
textuiand transfer the repository into it. That is possible but not free:softov/textuiand would need revoking and recreating againsttextui/textuisoftov.github.io/textuitotextui.github.io/textui, andhomepagein six manifests points at the old onerepository.urlin the manifests changesNot worth it for a sidebar entry, in my view — but it is a real option if the
@textuiGitHub org is something you want anyway for other reasons.