Component Namespaces

Component tags resolve by filename, so two libraries that both ship a Button.html collide. Namespaces let you say which one you meant.

If you only have one component library you will never need this page.

Registering a library

A library claims a namespace once, in its own root component. That registers every component in the folder under that name:

source 
<!-- components/flowbite/index.ts -->
<script>
components.set("flowbite")  // Register this folder as "flowbite" namespace
</script>

Or map the folder in jaf.config.js instead, with namespaces.libraries. See Configuration.

Picking one

Three ways, from most local to least.

On the tag, for a one-off:

source 
<!-- Explicit namespace at point-of-use -->
<Button:flowbite>Uses Flowbite's Button</Button:flowbite>
<Button:shadcn>Uses Shadcn's Button</Button:shadcn>
<Button>Uses default resolution</Button>

Per component, to mix two libraries in one file:

source 
<!-- Mix components from different libraries -->
<script>
components("Button", "flowbite")
components("Card", "shadcn")
</script>

<Card>
  <Button>Flowbite button inside Shadcn card</Button>
</Card>
<Alert>Uses normal tree-walk resolution</Alert>

For the whole file, when it belongs to one library:

source 
<!-- pages/admin/dashboard.html -->
<script>
components("flowbite")  // All components default to flowbite
</script>

<Button>Resolves to flowbite's Button</Button>
<Card>Resolves to flowbite's Card</Card>
<Modal>Resolves to flowbite's Modal</Modal>

components() and components.set() are compile-time directives. The compiler reads them and strips the calls.

Resolution order

Priority Source Looks like
1 On the tag <Button:flowbite>
2 An import statement import { Button } from "..."
3 Per-component alias components("Button", "flowbite")
4 File preference components("flowbite")
5 Tree walk Nearest matching file

Collision warnings

When two files claim the same component name, the build says so and the dev runtime names the file it picked:

source 
[jaf] Duplicate component names detected:
  Button:
    - components/flowbite/Button.html
    - components/shadcn/Button.html
    - pages/admin/components/Button.html

  Consider using namespacing to disambiguate.
source 
[jaf] Resolved <Button> to components/flowbite/Button.html
      Other candidates:
        - components/shadcn/Button.html
      Use <Button:namespace> or components() to be explicit.

Turn the build warning off with namespaces.warnOnConflicts: false.