ReviewOS

stacks/stx

docs(@stacksjs/components): lead README with the JSX-tag form, not @component directives

#1688
Closed glennmichael123 opened this 23 days ago · 0 comments
23 days ago

The @stacksjs/components README leads its ## Usage section with the verbose @component('Foo', {...}) Blade-style directive form, but the actual example files in the same package (and other consumer code) use the much cleaner JSX-tag form. New users following the README write code like:

@component('Dialog', { open: isOpen, onClose: close })
  @component('DialogBackdrop')

  @component('DialogPanel', { className: 'max-w-md' })
    @component('DialogTitle')
      Confirm delete
    @endcomponent
  @endcomponent
@endcomponent

…when the actual idiomatic stx form is:

<Dialog :open="isOpen" :onClose="close">
  <DialogBackdrop />
  <DialogPanel className="max-w-md">
    <DialogTitle>Confirm delete</DialogTitle>
  </DialogPanel>
</Dialog>

Where the inconsistency lives

FileForm used
packages/components/README.md § Usage / Basic Example@component(...) directive
packages/components/src/ui/dialog/README.md § Usage@component(...) directive
packages/components/examples/button-examples.stxJSX tags (<Button variant="primary">)
packages/components/examples/input-examples.stxJSX tags
packages/components/examples/demo.stxmostly @component(...) directive (mixed)

A reader hitting the README first reasonably concludes the directive form is the API. They write 30 lines of @component(...) boilerplate before discovering the example files do it differently.

Suggested change

Make the JSX-tag form the canonical example throughout, with @component(...) mentioned once as a Blade-compat alternative. Concretely:

  1. Rewrite packages/components/README.md "Basic Example" and per-component snippets to use JSX tags
  2. Rewrite src/ui/*/README.md (35 component readmes) the same way — biggest mechanical lift, but each is short
  3. Pick one form for examples/demo.stx (probably JSX) and stop mixing within a single file
  4. Add a one-liner near the top: "Both <Foo> and @component('Foo', {...}) work; the JSX form is preferred."

Why this matters

It's a subtle thing but it shapes the first impression of the library. The verbose form has a higher visual cost per usage and obscures simple things — a five-line modal becomes 15 lines of nested directives. New apps end up with a lot more code than they need.

I'm not asking to remove the directive form (it's a valid Blade-compat path), just to lead with the cleaner one.

Context

Hit while migrating an app to use @stacksjs/components. Came in expecting the JSX shape (matches <StxLink>, <Icon>, custom auto-discovered components, the rest of the stx ecosystem); got told by the README to write Blade directives; later found the real example files using JSX tags; spent a beat wondering if the JSX form was actually supported or just an experiment.

Sign in to comment on this issue.