@itrocks/ux-core

v0.1.3

Published

23 days ago

UI component providing a basic it.rocks app container with navigation, title bar, and logout support

0High
0Medium
0Low

baptistepillot

backend header it.rocks layout menu navigation shell sidebar UI UX

ux-core

UI component providing a basic it.rocks app container with navigation, title bar, and logout support.

This documentation was written by an artificial intelligence and may contain errors or approximations. It has not yet been fully reviewed by a human. If anything seems unclear or incomplete, please feel free to contact the author of this package.

Installation

npm i @itrocks/ux-core

The package only ships static assets (CSS, fonts, icons). There is no JavaScript API.

In a browser page, include at least the main stylesheet:

<link href="/node_modules/@itrocks/ux-core/css/app.css" rel="stylesheet">

Depending on the page, you may also want article.css to get the standard article/form layout:

<link href="/node_modules/@itrocks/ux-core/css/article.css" rel="stylesheet">

Adjust paths according to how you serve static assets in your application.

Usage

@itrocks/ux-core provides a pre‑built application frame:

full‑height page layout using CSS Grid,
header, optional breadcrumb and collapse toggle,
left navigation menu,
main content area and footer,
optional global search and user/logout section.

You opt‑in simply by structuring your HTML according to the expected layout and including the CSS.

Minimal example

<!DOCTYPE html>
<html lang="en">
<head>
	<link href="/node_modules/@itrocks/ux-core/css/app.css" rel="stylesheet">
	<meta charset="utf-8">
	<title>My it.rocks app</title>
</head>
<body>
	<header>
		<h1>My application</h1>
	</header>
	<button class="collapse" type="button" aria-label="Toggle navigation"></button>
	<nav class="menu app">
		<ul>
			<li class="home"><h3>Home</h3></li>
		</ul>
	</nav>
	<main>
		<article>
			<header><h2>Welcome</h2></header>
			<p>Content goes here…</p>
		</article>
	</main>
	<footer>
		&copy; 2025 My company
	</footer>
</body>
</html>

This already gives you the default it.rocks look and feel: Roboto font, neutral header and sidebar background, and a responsive layout with a collapsible menu on small screens.

Complete example with breadcrumb, user and global search

Below is a more realistic page using several optional building blocks:

<!DOCTYPE html>
<html lang="en">
<head>
	<link href="/node_modules/@itrocks/ux-core/css/app.css" rel="stylesheet">
	<link href="/node_modules/@itrocks/ux-core/css/article.css" rel="stylesheet">
	<meta charset="utf-8">
	<title>Orders</title>
</head>
<body>
	<header>
		<h1>Back‑office</h1>
		<section class="user authenticated user">
			<span class="name">John Doe</span>
			<a href="/logout">Logout</a>
		</section>
	</header>

	<button class="collapse" type="button" aria-label="Toggle navigation"></button>

	<ol class="breadcrumb">
		<li><a href="/">Home</a></li>
		<li><a href="/orders">Orders</a></li>
	</ol>

	<nav class="menu app">
		<ul>
			<li class="administration">
				<h3>Administration</h3>
				<ul>
					<li><a href="/users">Users</a></li>
					<li><a href="/roles">Roles</a></li>
				</ul>
			</li>
		</ul>
	</nav>

	<main>
		<article data-action="list" data-class="Order" data-route="/orders">
			<header>
				<h2>Orders</h2>
				<section class="summary">123 elements</section>
				<ul class="general actions">
					<li class="new"><a href="/orders/new">New order</a></li>
					<li class="close action close"><a href="/">Close</a></li>
				</ul>
			</header>
			<form name="global-search" action="/orders" method="get">
				<label for="q">Search</label>
				<input id="q" name="q" type="search" placeholder="Search orders…">
			</form>
			<section>
				<table class="objects">
					<!-- table body -->
				</table>
			</section>
			<footer>
				<ul class="selection actions">
					<li class="delete"><button type="submit" name="action" value="delete">Delete</button></li>
					<li class="close action close"><button type="button">Close</button></li>
				</ul>
			</footer>
		</article>
	</main>

	<footer>
		&copy; 2025 My company
	</footer>
</body>
</html>

The markup above is intentionally close to what is generated by higher‑level it.rocks packages such as @itrocks/list, so you can easily plug your own custom pages into the same visual language.

API

@itrocks/ux-core exposes a CSS‑based API. There are no JavaScript exports; instead, behaviour is controlled by the HTML structure and CSS class names you use.

Below is an overview of the main building blocks.

Global styles

Loaded via app.css:

Normalizes browser defaults using normalize.css.
Sets the default font to Roboto, sans-serif.
Sets a neutral text color (#444) and default font size (12px).
Applies box-sizing: border-box globally.

These global styles are applied automatically when you include app.css.

Page grid layout (`body`)

The body element is turned into a CSS Grid to organise the high‑level regions:

grid areas: header, collapse, breadcrumb, menu, main, footer.
full‑viewport height using the --real-vh custom property (or 100vh by default).

Expected direct children of body:

header – top bar of the application (title, user info, main actions).
.collapse – button used to toggle the collapsed state of the sidebar and header on small screens.
.breadcrumb – ordered list for the navigation path.
.menu – left navigation menu; when combined with .app it is treated as the application menu.
main – main content container.
footer – optional footer for legal mentions or application metadata.

Within main:

consecutive main children are separated with a border on the top and left, so multiple panes can be stacked.
.main.logo can be used as a placeholder pane displaying the it.rocks logo.

Breadcrumb (`.breadcrumb`)

Selector: body > .breadcrumb.

Expected element: <ol class="breadcrumb"> or <ul class="breadcrumb">.
Children: list items (<li>) optionally containing links.
A > separator is automatically added between items using ::before.

Additionally, for content pages, the internal h2 titles inside main headers are hidden at the top level to avoid repeating the breadcrumb.

Collapse toggle (`.collapse`)

Selectors:

body > .collapse – the visible button.
body.collapse – a state class applied to body when the layout is collapsed.

Behaviour (purely visual, you toggle the collapse class yourself via JS):

the .collapse button displays a back arrow (action/back.svg),
when body has the collapse class:
- the button uses a burger/menu icon (action/menu.svg),
- the header and .app.menu sidebar are collapsed to width 0.
on small screens (max-width: 600px), when not collapsed:
- the sidebar takes almost the full viewport width,
- breadcrumb and #notifications are hidden,
- main is reduced to the width of the collapse button and its content is faded out.

Your JavaScript should simply add or remove the collapse class on body when the user clicks the button.

Article / form layout (`article.css`)

Selectors:

main > article
main > form

These are displayed as a three‑row grid: header, content, footer.

Structure:

header or a bare h2 becomes the top row.
Any child that is not a footer, h2, or header becomes scrollable content.
A nested header > h2 gets the standard section title styling (grey background, border, padding).
Direct p children get a reasonable default margin.

Use this layout for any page that behaves like a self‑contained panel (lists, forms, detail pages, etc.).

Global search form (`form[name="global-search"]`)

Selector: form[name=global-search].

Intended to live inside an article or main content area.
Hidden by default (display: none); you can reveal it when needed (for example by toggling a class via JavaScript).
The text input grows to use the full width of the form.
The associated label is visually hidden.

Typical integration is to place the form near the top of an article and toggle its visibility when a "Search" action is triggered.

User block (`.authenticated.user`)

Selector: .authenticated.user.

This is designed to render the currently authenticated user in the application header.

Expected structure:

<section class="user authenticated user">
	<span class="name">John Doe</span>
	<a href="/logout">Logout</a>
</section>

Behaviour:

The .name element is hidden, so only the action link is visible.
The <a> link:
- shows a user icon on the left,
- has increased font size,
- has hover feedback via a light background.

You are free to change the link target (logout, profile page, etc.) while keeping the same styling.

Close action (`.action.close`, `.actions > .close`)

Selectors:

.action.close
.actions > .close

Any action element with these classes gets a standard close icon as a background image (action/close.svg).

This is typically used in action toolbars built by other it.rocks components, but you can reuse it for your own buttons or links.

Typical use cases

Base layout for an it.rocks back‑office – structure every page with the same header, sidebar menu, main content and footer, and let higher‑level components plug their HTML into the main area.
Consistent list and form pages – use article.css so lists, edit forms, detail views, and confirmation pages share the same grid layout and header/footer styling.
Responsive collapsible sidebar – wire a small JavaScript handler to toggle the collapse class on body and get a responsive navigation experience with very little code.
Shared breadcrumb and notifications – render a .breadcrumb list and a #notifications container at the top of body and let the CSS handle alignment and overflow on small screens.
Reusable user/logout header – display the authenticated user and logout action with .authenticated.user, keeping a consistent icon and spacing across applications.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

ux-core

Installation

Usage

Minimal example

Complete example with breadcrumb, user and global search

API

Global styles

Page grid layout (body)

Breadcrumb (.breadcrumb)

Collapse toggle (.collapse)

Article / form layout (article.css)

Global search form (form[name="global-search"])

User block (.authenticated.user)

Close action (.action.close, .actions > .close)

Typical use cases

Page grid layout (`body`)

Breadcrumb (`.breadcrumb`)

Collapse toggle (`.collapse`)

Article / form layout (`article.css`)

Global search form (`form[name="global-search"]`)

User block (`.authenticated.user`)

Close action (`.action.close`, `.actions > .close`)