Catalog class

`class` `Catalog`

Manager of the components and their global settings.

Catalog(
    folder: str | pathlib._local.Path | None = None,
    *,
    jinja_env: jinja2.environment.Environment | None = None,
    extensions: list | None = None,
    filters: dict[str, typing.Any] | None = None,
    tests: dict[str, typing.Any] | None = None,
    auto_reload: bool = True,
    asset_resolver: collections.abc.Callable[[str, str], str] | None = None,
    **globals: Any
) -> None

Argument	Description
`folder`	Optional folder path to scan for components. It's a shortcut to calling `add_folder` when only one is used.
`jinja_env`	Optional Jinja2 environment to use for rendering.
`extensions`	Optional extra Jinja2 extensions to add to the environment.
`filters`	Optional extra Jinja2 filters to add to the environment.
`tests`	Optional extra Jinja2 tests to add to the environment.
`auto_reload`	Whether to check the last-modified time of the components files and automatically re-process them if they change. The performance impact of leaving it on is minimal, but might be noticeable when rendering a component that uses a large number of child components.
`asset_resolver`	Optional callable that transforms asset URLs for components from folders registered with an `assets` folder. Receives `(url, prefix)` and returns the resolved URL. Only invoked for components whose prefix has a registered assets folder; all other asset URLs pass through unchanged.
`**globals`	Variables to make available to all components by default.

`function` `add_folder`

Add a folder path from which to search for components, optionally under a prefix.

add_folder(
    path: str | pathlib._local.Path,
    *,
    prefix: str = '',
    assets: str | pathlib._local.Path | None = None
) -> None

Argument	Description
`path`	Absolute path of the folder with component files.
`prefix`	Optional path prefix that all the components in the folder will have. The default is empty.
`assets`	Optional path to a folder containing CSS/JS assets for this folder's components. When set, the `asset_resolver` will be invoked for asset URLs from these components.

Components without a prefix can be imported as a path relative to the folder, e.g.: sub/folder/component.jinja or with a path relative to the component where it is used: ./folder/component.jinja.

Relative imports cannot go outside the folder.

Components added with a prefix must be imported using the @prefix/ syntax: @prefix/sub/folder/component.jinja. If the importing is done from within a component with the prefix itself, a relative import can also be used, e.g.: ./component.jinja.

All the folders added under the same prefix will be treated as if they were a single folder. This means if you add two folders, under the same prefix, with a component with the same subpath/filename, the one in the folder added first will be used and the other ignored.

WARNING: You cannot move or delete components files from the folder after calling this method, but you can call it again to add new components added to the folder.

`function` `add_package`

add_package(
    package_name: str,
    *,
    prefix: str
) -> None

Argument	Description
`package_name`	The importable package name (e.g. `"my_ui_kit"`).
`prefix`	Prefix for the components (e.g. `"ui"`).

The package module must expose a JX_COMPONENTS attribute pointing to the components folder (e.g. via importlib.resources.files). It may also expose JX_ASSETS pointing to an assets folder.

`function` `add_folder`

Add a folder path from which to search for components, optionally under a prefix.

add_folder(
    path: str | pathlib._local.Path,
    *,
    prefix: str = '',
    assets: str | pathlib._local.Path | None = None
) -> None

Argument	Description
`path`	Absolute path of the folder with component files.
`prefix`	Optional path prefix that all the components in the folder will have. The default is empty.
`assets`	Optional path to a folder containing CSS/JS assets for this folder's components. When set, the `asset_resolver` will be invoked for asset URLs from these components.

Components without a prefix can be imported as a path relative to the folder, e.g.: sub/folder/component.jinja or with a path relative to the component where it is used: ./folder/component.jinja.

Relative imports cannot go outside the folder.

WARNING: You cannot move or delete components files from the folder after calling this method, but you can call it again to add new components added to the folder.

`function` `collect_assets`

Copy all registered package assets to an output folder.

collect_assets(
    output: str | pathlib._local.Path
) -> list[tuple[str, pathlib._local.Path]]

Argument	Description
`output`	Destination folder.

For each prefix that has a registered assets folder, files are copied to <output>/<prefix>/. Returns a list of (prefix, relative_path) tuples for every file copied.

`function` `get_assets_folder`

Return the registered assets folder for a given prefix, or None.

get_assets_folder(
    prefix: str
) -> pathlib._local.Path | None

Argument	Description
`prefix`	The prefix to look up (e.g. `"ui"`).

`function` `get_component`

Instantiate and return a component object by its relative path.

get_component(
    relpath: str
) -> jx.component.Component

Argument	Description
`relpath`	The path of the component to render, including the extension, relative to its view folder. e.g.: "sub/component.jinja". Always use the forward slash (/) as the path separator.

`function` `get_component_data`

Get the component data from the cache. If the file has been updated, the component is re-processed.

get_component_data(
    relpath: str
) -> jx.catalog.CData

Argument	Description
`relpath`	The path of the component to render, including the extension, relative to its view folder. e.g.: "sub/component.jinja". Always use the forward slash (/) as the path separator.

`function` `get_signature`

Return a component's signature including its arguments and metadata.

get_signature(
    relpath: str
) -> dict[str, typing.Any]

Argument	Description
`relpath`	The path of the component, including the extension, relative to its view folder. e.g.: "sub/component.jinja". Always use the forward slash (/) as the path separator.

Returns: A dictionary containing:

required: dict of required argument names mapped to their type (or None)
optional: dict of optional arguments mapped to (default_value, type or None)
slots: tuple of slot names
css: tuple of CSS file URLs
js: tuple of JS file URLs

`function` `list_components`

Return all registered component paths.

list_components() -> list[str]

Returns: A list of component relative paths (e.g., ["button.jinja", "card.jinja"]).

`function` `render`

Render a component with the given relative path and context.

render(
    relpath: str,
    globals: dict[str, typing.Any] | None = None,
    **kwargs
) -> str

Argument	Description
`relpath`	The path of the component to render, including the extension, relative to its view folder. e.g.: "sub/component.jinja". Always use the forward slash (/) as the path separator.
`globals`	Optional global variables to make available to the component and all its imported components.
`**kwargs`	Keyword arguments to pass to the component. They will be available in the component's context but not to its imported components.

Returns: The rendered component as a string.

`function` `render_string`

Render a component from a string source. Works like render, but the component is not cached and cannot do relative imports.

render_string(
    source: str,
    globals: dict[str, typing.Any] | None = None,
    **kwargs
) -> str

Argument	Description
`source`	The Jinja2 source code of the component to render.
`globals`	Optional global variables to make available to the component and all its imported components.
`**kwargs`	Keyword arguments to pass to the component. They will be available in the component's context but not to its imported components.

Returns: The rendered component as a string.

Catalog class

class Catalog

function add_folder

function add_package

function add_folder

function collect_assets

function get_assets_folder

function get_component

function get_component_data

function get_signature

function list_components

function render

function render_string

`class` `Catalog`

`function` `add_folder`

`function` `add_package`

`function` `add_folder`

`function` `collect_assets`

`function` `get_assets_folder`

`function` `get_component`

`function` `get_component_data`

`function` `get_signature`

`function` `list_components`

`function` `render`

`function` `render_string`