open-index/open-npm huggingface dataset:
npm package: @illiastadnyk/randomid-generator
Description: Prosty moduł Node.js do generowania losowych identyfikatorów.
Latest version: 1.0.1

# random-id-generator

Prosty moduł Node.js do generowania losowych identyfikatorów.

## Instalacja

```bash
npm install @illiastadnyk/randomid-generator
or
yarn add @illiastadnyk/randomid-generator
npm package: @illidanj/cron-editor
Description: vue 的 cron 组件，支持解析/反解析 cron 表达式，生成最近五次的符合条件时间
Author: illidanj
Latest version: 1.0.3

![](public/demo.png)

# vue-crontab

vue 的 cron 组件，支持解析/反解析 cron 表达式，生成最近五次的符合条件时间，依赖 vue2 和 element-ui

根据小石头的项目进行二次开发，修复部分bug

## 安装方式

```
npm install @illidanj/cron-editor
```

## 引入方式

```javascript
//全局引入
import vcrontab from "@illidanj/cron-editor";
Vue.use(vcrontab); //使用方式：<vcrontab></vcrontab>

//单独引入
import vcrontab from "@illidanj/cron-editor";
export default {
  components: { vcrontab },
};
```

## 代码示例

```javascript
<template>
    <div id="app">
        <div class="box">
            <el-input v-model="input" placeholder class="inp"></el-input>
            <el-button type="primary" @click="showDialog">生成 cron</el-button>
        </div>
        <el-dialog title="生成 cron" :visible.sync="showCron">
            <vcrontab @hide="showCron=false" @fill="crontabFill" :expression="expression"></vcrontab>
        </el-dialog>
    </div>
</template>

<script>
import vcrontab from 'cronEditor'
export default {
    components: { vcrontab },
    data() {
        return {
            input: "",
            expression: "",
            showCron: false
        };
    },
    methods: {
        crontabFill(value) {
            //确定后回传的值
            this.input = value;
        },
        showDialog() {
            this.expression = this.input;//传入的 cron 表达式，可以反解析到 UI 上
            this.showCron = true;
        }
    }
};
</script>
```

## 参数

- expression
  传入的 cron 表达式，可以反解析到 UI 上

- hideComponent
  需要隐藏的组件数组，依次为`['second','min','hour','day','mouth','week','year']`
  
- defaultExpression
  默认cron表达式，重置后cron会被设置为该值，默认为 `* * * * * ?`

## 方法

- fill
  点击确定时，把选择好的值返回。

- hide
  关闭组件时的回调
npm package: @illidian/ytcap
Description: CLI for fetching YouTube video metadata and transcripts
Latest version: 0.1.0

# ytcap

CLI for fetching YouTube video metadata and transcripts.

## Install

```bash
npm install
python3 -m pip install --user yt-dlp youtube-transcript-api
npm run build
```

On Windows, use `py` instead of `python3` if needed:

```powershell
npm install
py -m pip install --user yt-dlp youtube-transcript-api
npm run build
```

## Usage

Check local runtime:

```bash
node dist/src/index.js doctor --format json
```

Fetch a video's metadata and transcript:

```bash
node dist/src/index.js fetch --url "https://www.youtube.com/watch?v=dQw4w9WgXcQ" --lang en --format json
```

Global install from npm:

```bash
npm install -g @illidian/ytcap --registry https://registry.npmjs.org/
```

The command writes output under `youtube-output/<video-id>/`:

- `metadata.json`
- `transcript.json`
- `transcript.txt`

## Proxy

If your machine reaches YouTube through a local proxy, set standard proxy environment variables before running the CLI:

```bash
export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890
```

PowerShell:

```powershell
$env:HTTP_PROXY='http://127.0.0.1:7890'
$env:HTTPS_PROXY='http://127.0.0.1:7890'
```

## Commands

```text
ytcap doctor [--format json|table|yaml]
ytcap fetch --url <youtube-url> [--lang <language>] [--output <directory>] [--format json|table|yaml]
```
npm package: @illinois-grad/codex
Description: Domain-specific utilities for Graduate College applications including terms and programs
Author: Mikael Arvola
Latest version: 2.0.14

# @illinois-grad/codex

Domain-specific utilities for Graduate College applications including terms and programs.

## Installation

```bash
npm install @illinois-grad/codex
```

## API Reference

### Term Types and Interfaces

#### `Term`

```typescript
interface Term {
  year: number;                        // Four digit year
  month: number;                       // 1=Spring, 5=Summer, 8=Fall
  name: "Spring" | "Summer" | "Fall" | "Unknown";
  gradMonthName: "May" | "Aug" | "Dec" | "Unknown";
  code: string;                        // Format: "1YYYYX"
  academicYear: string;                // e.g., "2023-2024"
  termName: string;                    // e.g., "Spring 2024"
  shortTermName: string;               // e.g., "SP 24"
}
```

### Term Functions

- `parseTermCode(code: string, returnDefault?: boolean): Term`
- `generateTermCode(year: number, month: number): string`
- `createTerm(year: number, monthInput: number | Term["name"] | Term["gradMonthName"]): Term`
- `getCurrentTerm(): Term`
- `getCurrentTermCode(): string`
- `monthToTermName(month: number): Term["name"]`
- `monthToGradMonthName(month: number): Term["gradMonthName"]`

## Program Functions

- `splitProgramCode(programCode: string): ProgramCodeParts`
- `formatProgramCode(programCode: string, options?: { separator?: string }): string`
- `isValidProgramCode(programCode: string): boolean`
- `buildProgramCode(parts: ProgramCodeParts): string`
npm package: @illinois-grad/grad-vue-rte
Description: Rich text editor components for Graduate College apps using Tiptap.
Author: University of Illinois Graduate College
Latest version: 2.5.5

# @illinois-grad/grad-vue-rte

Rich Text Editor components for Graduate College apps using [Tiptap](https://tiptap.dev/).

This is a companion package to `@illinois-grad/grad-vue` that provides components which depend on rich text editing capabilities. By keeping these components in a separate package, we keep the main library lightweight for projects that don't need rich text editing features.

## Features

- **Vue 3**: Built with Vue.js version 3 and the Composition API.
- **Tiptap Integration**: Uses Tiptap for rich text editing capabilities.
- **Accessibility-First**: All components are built with consideration for all users.

## Installation

```bash
npm install @illinois-grad/grad-vue-rte
```

**Note:** This package has peer dependencies on several Tiptap packages which will be installed automatically.

## Usage

### Import All Components In Vue.js

```javascript
import { createApp } from 'vue'
import GradVueRTE from '@illinois-grad/grad-vue-rte'
import '@illinois-grad/grad-vue-rte/grad-vue-rte.css'
import App from './App.vue'

const app = createApp(App)
app.use(GradVueRTE)
```

### Import All Components in Nuxt.js

Add `grad-vue-rte.ts` into your plugins folder:

```javascript
import GradVueRTE from '@illinois-grad/grad-vue-rte';
import '@illinois-grad/grad-vue-rte/grad-vue-rte.css';

export default defineNuxtPlugin(async (nuxt) => {
    nuxt.vueApp.use(GradVueRTE);
});
```

### Import Individual Components

```javascript
import { GChatInput } from '@illinois-grad/grad-vue-rte'
import '@illinois-grad/grad-vue-rte/grad-vue-rte.css'
```

## Components

### GChatInput

A chat input component with rich text editing capabilities.

**Props:**
- `placeholder` (string, default: "Type a comment"): Placeholder text for the input
- `disabled` (boolean, default: false): Whether the input is disabled
- `maxRows` (number, default: 5): Maximum number of rows for the editor
- `label` (string, default: "Comment input"): Accessible label for the editor

**Events:**
- `send`: Emitted when the user presses Enter (without Shift) or clicks the send button

**v-model:**
- Binds to the editor content as a Tiptap JSON object

**Example:**

```vue
<template>
  <GChatInput 
    v-model="comment"
    placeholder="Enter your comment"
    @send="handleSend"
  />
</template>

<script setup>
import { ref } from 'vue'
import { GChatInput } from '@illinois-grad/grad-vue-rte'

const comment = ref('')

function handleSend(content) {
  console.log('Comment sent:', content)
  comment.value = ''
}
</script>
```

## Development

This package is part of the grad-vue monorepo. See the main [README](../../README.md) for development instructions.

## License

MIT - University of Illinois Graduate College
npm package: @illinois-grad/vue-auth
Description: Vue 3 authentication utilities with MSAL integration for Graduate College applications
Author: Mikael Arvola
Latest version: 2.0.14

# @illinois-grad/vue-auth

Vue 3 authentication utilities with MSAL (Microsoft Authentication Library) integration for Graduate College applications.

## Features

- **MSAL Integration** - Complete Entra/Microsoft authentication support
- **Reactive** - Built with Vue 3 Composition API
- **Router Guards** - Protect routes with authentication
- **User Utilities** - Helper functions for user display and avatars
- **Type Safe** - Written in TypeScript with full type definitions

## Installation

```bash
npm install @illinois-grad/vue-auth
```

### Peer Dependencies

This package requires the following peer dependencies:

```json
{
  "@azure/msal-browser": "^4.0.0",
  "pinia": "^3.0.0",
  "vue": "^3.0.0",
  "vue-router": "^4.0.0"
}
```
npm package: @illinois-grad/vue-datetime
Description: Vue 3 datetime formatting utilities for Graduate College applications
Author: Mikael Arvola
Latest version: 2.0.14

# @illinois-grad/vue-datetime

Vue 3 datetime formatting utilities for Graduate College applications.

## Installation

```bash
npm install @illinois-grad/vue-datetime
```

### Peer Dependencies

This package requires the following peer dependencies:

```json
{
  "vue": "^3.0.0"
}
```

## Usage

### Basic Date Formatting

```typescript
import { formatDate } from '@illinois-grad/vue-datetime'

// Full format (default)
formatDate('2024-01-15T10:30:00Z')
// "Jan 15, 2024"

// With time
formatDate('2024-01-15T10:30:00Z', { includeTime: true })
// "Jan 15, 2024 10:30 AM"

// Short format
formatDate('2024-01-15T10:30:00Z', { shortFormat: true })
// "1/15" (if 2024 is the current year)

// Short format with year
formatDate('2023-01-15T10:30:00Z', { shortFormat: true })
// "1/15/2023"

// Handle null values
formatDate(null)
// "None"

// Custom null text
formatDate(null, { nullText: 'N/A' })
// "N/A"

// Invalid dates
formatDate('invalid-date', { invalidText: 'Unknown' })
// "Unknown"
```

### Preset Formatters

For convenience, the package provides preset formatters:

```typescript
import { 
  fullDateFormat,        // "Jan 15, 2024"
  shortDateFormat,       // "1/15" or "1/15/2024"
  fullDateTimeFormat,    // "Jan 15, 2024 10:30 AM"
  shortDateTimeFormat    // "1/15 10:30 AM" or "1/15/2024 10:30 AM"
} from '@illinois-grad/vue-datetime'

const date = '2024-01-15T10:30:00Z'

fullDateFormat(date)        // "Jan 15, 2024"
shortDateFormat(date)       // "1/15" (if current year)
fullDateTimeFormat(date)    // "Jan 15, 2024 10:30 AM"
shortDateTimeFormat(date)   // "1/15 10:30 AM" (if current year)
```

### Vue Composables

Use reactive composables in your Vue components:

```vue
<script setup lang="ts">
import { ref } from 'vue'
import { 
  useFullDateFormat, 
  useShortDateFormat,
  useFullDateTimeFormat,
  useShortDateTimeFormat,
  useDateFormat
} from '@illinois-grad/vue-datetime'

const date = ref('2024-01-15T10:30:00Z')

// Preset composables
const fullDate = useFullDateFormat(date)
const shortDate = useShortDateFormat(date)
const fullDateTime = useFullDateTimeFormat(date)
const shortDateTime = useShortDateTimeFormat(date)

// Custom composable with options
const customFormat = useDateFormat(date, {
  shortFormat: true,
  includeTime: true,
  yearAware: false  // Always show year
})
</script>

<template>
  <div>
    <p>Full Date: {{ fullDate }}</p>
    <!-- "Jan 15, 2024" -->
    
    <p>Short Date: {{ shortDate }}</p>
    <!-- "1/15" or "1/15/2024" -->
    
    <p>Full Date Time: {{ fullDateTime }}</p>
    <!-- "Jan 15, 2024 10:30 AM" -->
    
    <p>Short Date Time: {{ shortDateTime }}</p>
    <!-- "1/15 10:30 AM" or "1/15/2024 10:30 AM" -->
    
    <p>Custom: {{ customFormat }}</p>
    <!-- "1/15/2024 10:30 AM" (year always shown) -->
  </div>
</template>
```
npm package: @illinois-grad/vue-useful-api
Description: Vue 3 API integration utilities with reactive state management for Graduate College applications
Author: Mikael Arvola
Latest version: 2.0.14

# @illinois-grad/vue-useful-api

Vue 3 API integration utilities with reactive state management for Graduate College applications.

## Features

- **Reactive State** - Automatic loading, error, and response state management
- **Event Hooks** - onSuccess, onError, and onFinally callbacks
- **Request Deduplication** - Ignores stale responses automatically
- **Auto-execution** - apiWatch composable for reactive API calls
- **Error Handling** - User-friendly error messages with type guards
- **Type Safe** - Written in TypeScript with full type definitions

## Installation

```bash
npm install @illinois-grad/vue-useful-api
```

### Peer Dependencies

This package requires the following peer dependencies:

```json
{
  "vue": "^3.0.0"
}
```

## Usage

### Automatic Execution with apiWatch

The `apiWatch` composable automatically executes API calls when reactive dependencies change:

```typescript
import { ref } from 'vue'
import { usefulApi, apiWatch } from '@illinois-grad/vue-useful-api'
import { useUsersApi } from './users'

const userId = ref('123')
const includeDetails = ref(true)

const users = useUsersApi();
const me = users.getMe();

apiWatch(me.execute, () => {
    if (auth.isAuthenticated) {
        return [userId.value, includeDetails.value];
    }
    // Return undefined to skip execution
    return undefined;
});

// The response is reactive
const profile = computed(() => {
    return me.response.value?.userInfo;
});

// You can also use event hooks
me.onSuccess((user) => {
  console.log('User loaded:', user)
})

// Now whenever userId or includeDetails changes, the API is called automatically
userId.value = '456' // Triggers API call with new ID
includeDetails.value = false // Triggers API call with new details flag

// The error state is also reactive
me.error.value // null if no error

// And errors have events
me.onError((error) => {
  console.error('Failed to load user:', error)
});

// The loading state is also reactive
me.isLoading.value // false if finished
```
npm package: @illinois-toolkit/ilw-back-to-top
Description: Illinois Toolkit: The Illinois component back-to-top allows you to provide a simple way to skip either to the top of a page or to a designated point in the page (such as the page content area).
Latest version: 1.2.1

# ilw-back-to-top
## Overview
This component places a button in the bottom-right corner of the screen which takes visitors back to the top of the page. It uses animation that simulates vertical scrolling while not being overwhelming for motion-sensitive viewers.

This component should be placed as close as possible to the ending `</body>` tag, outside of any `<ilw-page>` element in use.

By default, this component will take the visitor to the top edge of the page. To change the location of the top of the page, use the `target` attribute.

## Code Examples

Placement
```html
<body>
  <ilw-page>

  <!-- ... page content ... -->

  </ilw-page>
  <ilw-back-to-top></ilw-back-to-top>
</body>
```
To change the location of the top of the page, use the `target` attribute:

```html
<ilw-page>
  
  <div id="my-top-of-page"></div>
  
</ilw-page>
<ilw-back-to-top target="my-top-of-page"></ilw-back-to-top>
```

To change the position of the button, modify the `ilw-back-to-top--right` and `ilw-back-to-top--bottom` CSS variables. These control the distance from the button to the right and bottom edges of the screen, respectively.

```css
ilw-back-to-top {
  --ilw-back-to-top--right: 48px;
  --ilw-back-to-top--bottom: 48px;
}
```
## Upgrade Process
Rename il-back-to-top to ilw-back-to-top.
## External References
https://www.nngroup.com/articles/back-to-top/
npm package: @illinois-toolkit/ilw-breadcrumbs
Description: Illinois Toolkit: a list of formatted links that provide the path between the site’s home page and the page the reader is currently viewing.
Latest version: 1.3.3

# ilw-breadcrumbs

Links: **[ilw-breadcrumbs in Builder](https://builder3.toolkit.illinois.edu/component/ilw-breadcrumbs/index.html)** | 
[Illinois Web Theme](https://webtheme.illinois.edu/) | 
[Toolkit Development](https://github.com/web-illinois/toolkit-management)

## Overview

The Illinois components implementation of breadcrumbs provides a list of formatted links that provide the path between the site’s home page and the page the reader is currently viewing.

The site’s home page should be the first link in the list of breadcrumbs and should link to the site root. Pages used to navigate between the home page and the current page should also be listed and linked.

The current page item should not be linked, since following a link to the current page would just reload the page.


## Code Example
```html
<ilw-breadcrumbs>
    <a href="/">Home</a>
    <a href="/academics">Academics</a>
    <a href="/academics/undergraduate">Undergraduate programs</a>
    <span>Degree programs</span>
</ilw-breadcrumbs>
```
## Upgrade Process
* Rename ```il-breadcrumbs``` to ```ilw-breadcrumbs```
* Remove ```il-breadcrumbs-page``` tag and replace it with an anchor ```a``` tag
* For the current page, remove ```il-breadcrumbs-page``` tag and replace it with ```span``` tag

## External References

https://www.w3.org/WAI/ARIA/apg/patterns/breadcrumb/

https://www.nngroup.com/articles/breadcrumbs/
npm package: @illinois-toolkit/ilw-call-to-action
Description: Illinois Toolkit: The call to action component is used to prompt visitors to perform an action or a few related actions, such as subscribing to a newsletter or beginning an application.
Latest version: 1.1.0

# ilw-call-to-action

Links: **[ilw-call-to-action in Builder](https://builder3.toolkit.illinois.edu/component/ilw-call-to-action/index.html)** | 
[Illinois Web Theme](https://webtheme.illinois.edu/) | 
[Toolkit Development](https://github.com/web-illinois/toolkit-management)

## Overview

The call to action component is used to prompt visitors to perform an action or a few related actions, such as subscribing to a newsletter or beginning an application.

It can contain a link or group of links and may include an icon. It uses a background that contrasts with content around it to draw attention and add visual separation.

By default, the call to action is shown with a gray background and start-aligned
text. There are a few attributes to control the component:

- The left side can have an icon using `slot="icon"`, which will move to be above
  the heading in smaller screen sizes.
- Color themes for `white`, `blue`, `blue-gradient`, `orange` and `orange-gradient`. For example, `theme="blue"`.
- Text content can be centered using `align="center"`. With large screen sizes,
  the icon slot will remain on the left, and the text center aligns in its 
  container.

## Code Examples

```html
<ilw-call-to-action>
    <img src="https://cdn.brand.illinois.edu/icons/solid/white/comment.svg" alt="" slot="icon">
    <h3>Training Opportunities</h3>
    <p>Need more in-depth guidance on building Illinois websites? Check out these resources.</p>
    <ul class="ilw-buttons">
        <li><a href="#">Brand training resources</a></li>
        <li><a href="#">Web components guides</a></li>
    </ul>
</ilw-call-to-action>
```

## Accessibility Notes

- Make sure to use the **correct heading level** in relation to the call to
  action's position in the page.
- The **icon** should always be decorative, and as such should have an empty
  `alt=""` attribute. For inline `svg`, use `aria-hidden="true"`.
- **Centered text** can be harder to read, so avoid using longer text when
  center aligning.
- Make sure links and buttons are descriptive.

## Upgrade Process

When upgrading from the v2 toolkit component, the following changes are needed:

- Rename all `il-call-to-action` to `ilw-call-to-action`.
- Replace uses of the theme classes with an attribute:
  - `class="il-theme-gray"` -> `theme="gray"`
  - `class="il-theme-blue"` -> `theme="blue"`
  - `class="il-theme-white"` -> `theme="white"`
  - `class="il-theme-blue-gradient"` -> `theme="blue-gradient"`
- Replace uses of the alignment classes with an attribute:
  - `class="il-align-left"` -> `align="left"`
  - `class="il-align-center"` -> `align="center"`
npm package: @illinois-toolkit/ilw-icon
Description: A wrapper class to pull the icons from https://cdn.brand.illinois.edu/icons.html
Latest version: 1.2.0

# ilw-icon

Links: **[ilw-icon in Builder](https://builder3.toolkit.illinois.edu/component/ilw-icon/index.html)** |
[Illinois Web Theme](https://webtheme.illinois.edu/) |
[Toolkit Development](https://github.com/web-illinois/toolkit-management)

## Overview

Renders icons from https://cdn.brand.illinois.edu/icons.html through the use of a web font, which means it follows
text color and font size from CSS.

Attributes include:

* `icon`: the icon name. If there is no `icon`, it will display nothing. If using an icon name that does not have a
  corresponding icon in the design list, it may display an unknown character symbol.
* `type`: the icon type: consists of *solid* and *line*. Defaults to solid.
* `alt`: the alternate text used for the icon. If omitted, the icon is given the `aria-hidden` attribute, and
  is considered decorative.
* `size`: forces a specific font size on the icon. If omitted, normal CSS rules for font sizes apply.

There should be no child tags or text.

**Note** that this component does not provide the duo tone icon option, as that does not work well with font-based
icons.

## Code Examples

```html

<ilw-icon icon="twitter"></ilw-icon>

<ilw-icon icon="admissions" type="line" alt="Access admissions records"></ilw-icon>
```

## Accessibility Notes and Use

If you are using an icon with text, then you can omit the `alt` attribute on the `ilw-icon`, and it will be rendered
as a decorative element. If you are not using an icon with text, then the icon is
conveying information and should have an appropriate `alt` text.

There is a possible issue with Chrome where it caches the image and then the cached version CORS does not contain the
proper CORS information. See the hacksoft.io article below for details, but it requires a global fix on either our side
or the CDN.

If you are using the icons as navigation, consider adding the text next to the icon. What may look obvious (a diploma)
may be confusing for someone outside the University. Also ensure that your target size (what the user is clicking on) is
44 by 44 CSS pixels to meet accessibility requirements.

## External References

* https://www.w3.org/WAI/WCAG21/Techniques/aria/ARIA24
* https://lit.dev/docs/api/templates/#nothing
* https://en.wikipedia.org/wiki/Mystery_meat_navigation#Iconographic_navigation
* https://github.com/tancredi/fantasticon
npm package: @illinois-toolkit/ilw-icon-panel
Description: Icon panel component for the Illinois Web Toolkit.
Latest version: 1.0.1

# ilw-icon-panel

Links: **[ilw-icon-panel in Builder](https://builder3.toolkit.illinois.edu/component/ilw-icon-panel/index.html)** |
[Illinois Web Theme](https://webtheme.illinois.edu/) |
[Toolkit Development](https://github.com/web-illinois/toolkit-management)

## Overview

The icon panel is a panel of highlighted content that fits well among paragraphs of text. It is
essentially a smaller version of a Call to Action panel with an icon.

It can be used either as a prominent link with a description attached, or with a heading and content.

When used as a link, the link should be placed in the `slot="link"` slot.

The icon always stays on the left side of the panel, even on mobile devices. The size of the icon
is reduced and the spacing is tightened to fit the smaller screen.

### Icon

The icon is placed into the `icon` slot.

The icon panel is intended to use the [ilw-icon](https://github.com/web-illinois/ilw-icon) component
for placing the icons, but it can also use an `<img>` tag or any other method of displaying an icon.

### Attributes

- `theme="white"` uses a white background.
- `accent="orange"` or `accent="blue"` changes the accent color of the panel.

## Code Examples

### With a link and description

```html
<ilw-icon-panel>
    <ilw-icon slot="icon" icon="resources"></ilw-icon>
    <a href="#" slot="link">Graduate College Handbook (PDF)</a>
    <p>Complete details of academic policies and requirements pertaining to graduate students as well as administrative
        policy for programs, units and staff.</p>
</ilw-icon-panel>
```
### With a heading and content

```html
<ilw-icon-panel>
    <ilw-icon slot="icon" icon="students"></ilw-icon>
    <h3>Support success at all stages of the student lifecycle</h3>
    <p><strong>Our commitment to student success begins from day one.</strong></p>
    <p>Complete details of academic policies and requirements pertaining to graduate students as well as administrative
      policy for programs, units and staff.</p>
</ilw-icon-panel>
```

## Accessibility Notes and Use

Keep the following in mind when using the icon panel:

- The icon itself is decorative, so should be marked as such with `aria-hidden="true"`. Note that
  `ilw-icon` does this automatically.
- If using a heading, make sure it fits into the page's heading structure.

## External References

None.
npm package: @illinois-toolkit/ilw-page-title
Description: Illinois Toolkit: provides a background image and gradient overlay options for the text of the title of a particular web page.
Latest version: 1.2.1

# ilw-page-title

Links: **[ilw-page-title in Builder](https://builder3.toolkit.illinois.edu/component/ilw-page-title/index.html)** | 
[Illinois Web Theme](https://webtheme.illinois.edu/) | 
[Toolkit Development](https://github.com/web-illinois/toolkit-management)

## Overview

The Illinois theme component ilw-page-title provides a background image and gradient overlay options for the text of the title of a particular web page.

The page title should be added in an `<h1>` tag. The background image can be added using the slot "background". The image should be added as an `<img>` tag.

The default color theme is white text on a dark blue background. Other themes available are orange, blue, and white.

For a top-of-page component with more visual impact, see ilw-hero.

### Attributes
* width: no width attribute will make it fit the container, `full` will break the container and go full width, `auto` and `page` will break the container for the background only. 

* theme: Default is white text on a dark blue background. Other themes available are `orange`, `blue`, and `white`.

## Code Examples

```html
<ilw-page-title>
  <img src="background.png" alt="" slot="background">
  <h1>Graduate Programs</h1>
</ilw-page-title>
```
## Upgrade Process
* Rename `il-page-title` to `ilw-page-title`.

## External References
https://www.nngroup.com/articles/text-over-images/

https://www.smashingmagazine.com/2023/08/designing-accessible-text-over-images-part1/
npm package: @illinois-toolkit/ilw-pagination
Description: Illinois Toolkit: This is a navigation component for paged content.
Latest version: 1.1.2

# ilw-pagination

Links: **[ilw-pagination in Builder](https://builder3.toolkit.illinois.edu/component/ilw-pagination/index.html)** | 
[Illinois Web Theme](https://webtheme.illinois.edu/) | 
[Toolkit Development](https://github.com/web-illinois/toolkit-management)

## Overview

This is a navigation component for paged content. This contains First, Previous, a numbered set of pages with the current page highlighted, Next, and Last. 

There are no alternate themes to this. 

If there are more than 8 pages, it will automatically fill in an ellipsis to mark a gap in pages. 

Each item (First, Previous, Next, Last, and numbered pages) will link to the current page with a *page* parameter. You can change this parameter by using the `parameter` attribute. A page *https://illinois.edu/list/* with a pagination web component creates links like *https://illinois.edu/list?page=2*, *https://illinois.edu/list?page=3*, *https://illinois.edu/list?page=4*, etc. This component will respect other querystring items and not add a dbout *?* in the querystring. 

The `ilw-pagination` component has the following attributes:
* `label`: the label used for this page counter. Defaults to *Page List*. 
* `pages`: integer only, the total number of pages in the list. This is required. Note that if this is zero-based, you must count 0 as a page (so fifteen pages is 0-14).
* `page`: integer only, the current page. Defaults to *1*.
* `parameter`: the querystring parameter used to build the link, defaults to *page*. Note that if you change this, it will also change the `page` parameter appropriately. 
* `hidepagecount`: Boolean value, hide the *page x of y* value. 
* `zerostart`: Boolean value, determine if the page counting starts at 0 (this is a Drupal default). Defaults to false. 

## Code Examples

```html
<ilw-pagination label="Top Page List" pages="5" page="3"></ilw-pagination>
```

## Accessibility Notes and Use

This will wrap the ordered list in a `nav` section with the correct `aria-label`. If you have multiple pagination (like a top and bottom), be sure to use the `label` attribute to differentiate the different pagination controls. This will assign the current page with the `aria-current` attribute. This also includes a "page x of y" for easier navigation.

When handling pages, please allow the option to change the number of items per page directly. 

This is requiring a distinct URL as opposed to JavaScript or inline loading because this encourages a way to bookmark a specific page. 

The target for each page number is at least 24x24 pixels. The page numbers are fixed on the page so the buttons don't jump too much from page to page. 

## External References

* https://www.w3.org/WAI/WCAG21/Techniques/html/H99
* https://www.nngroup.com/articles/alternatives-pagination-listing-pages/
* https://www.nngroup.com/articles/item-list-view-all/
* https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-current
npm package: @illinois-toolkit/ilw-profile-list
Description: The profile list is a compact version of the profile, used in the directory component. 
Latest version: 1.1.1

# ilw-profile-list

Links: **[ilw-profile-list in Builder](https://builder3.toolkit.illinois.edu/component/ilw-profile-list/index.html)** | 
[Illinois Web Theme](https://webtheme.illinois.edu/) | 
[Toolkit Development](https://github.com/web-illinois/toolkit-management)

## Overview

The profile list is a compact version of the profile, used in the directory component. 

All four slots (`image`, `name`, `title`, and main) are required. 

If you use the circle image, make sure your image has roughly the same height and width. 

You can use the helper class `ilw-profile-list-container` to put this in an unordered list.  

### Attributes

* `circle`: This will change the image to a circle.
* `padding:` standard length / percentage CSS of padding around the components. 

## Code Examples

```html
<ilw-profile-list>
    <a slot="name" href="#">Smith, Jane</a>
    <img slot="image" src="/img/profile.webp" alt="Jane Smith">
    <div slot="title">Department of Redundancy Department</div>
    <div><a href="#">jsmith@illinois.edu</a> | <a href="#">(217) 123-4567</a></div>
</ilw-profile-list>
```

## Accessibility Notes and Use

This is using the standard font / background contrast, so color contrast shouldn't be an issue. 

Make sure you add a proper alt text for the image. Do not include "portrait of" or "picture of" because screen readers will recognize that this is an image. When possible, allow users to enter in their own alt text because people identifying how they want to be described is essential to self-image. 

Because this is most likely used to list people, please add these in an unordered list with the helper class `ilw-profile-list-container`. You can use the grid CSS to create grids and handle padding in between items.

```
    display: grid;
    grid-template-columns: repeat(auto-fill, minmax(350px, auto));
    column-gap: 20px;
    row-gap: 20px;
```

For the phone number, you may want to use the `&#8209;` character as a non-breaking hyphen. 

The name is first semantically, even though visually, the picture is first. This is to ensure that screen readers read the name first before a description of the person is read. 

## External References

None
npm package: @illinois-toolkit/ilw-quote
Description: This component represents a quote or testimontial, with optional attribution of author and source.
Latest version: 1.2.1

# ilw-quote

Links: **[ilw-quote in Builder](https://builder3.toolkit.illinois.edu/component/ilw-quote/index.html)** | 
[Illinois Web Theme](https://webtheme.illinois.edu/) | 
[Toolkit Development](https://github.com/web-illinois/toolkit-management)

## Overview

This component represents a quote or testimonial, with optional attribution of author and source. The quote or testimonial is intended to be intermixed with copy and the quote is highlighted and called out.

An open quotation mark is added automatically before the quote.

This component should not contain a heading element.

The quote should be contained within a paragraph element with the slot attribute set to "content". The author should be contained within a paragraph element with the slot attribute set to "author". The source should be contained within a cite element with the slot attribute set to "source".

The following attributes can be used to control the display of the quote:

- `font="sans"` will display the quote text with a sans-serif font.
- `size="medium"` and `size="large"` will increase the font sizes and spacing.
- `align="left"` and `align="right"` will align the text left or right, respectively. The default alignment is `center`. Note that right-aligned text should be used sparingly for better accessibility.

## Code Examples

```html
<ilw-quote>
    <p slot="content">Either university presses will embrace new technology and offer scholarly content in new forms
        to researchers and under new business models, or they will follow the music industry and spend
        all of their resources on trying to protect their territory &mdash; unsuccessfully.</p>
    <p slot="author">Laura Cerruti</p>
    <cite slot="source">Director of Digital Content Development, University of California Press, profiled in Against the Grain</cite>
</ilw-quote>
```

## Upgrade Process
* Rename `il-quote` to `ilw-quote`
* For the content, place it inside a `p` tag with a slot attribute `slot="content"`
* for the author, change `slot="attributed"` to `slot="author"`
* for the source, change `p` tag to `cite` tag and change `slot="secondary"` to `slot="source"`

## External References

https://developer.mozilla.org/en-US/docs/Web/HTML/Element/blockquote

https://theadminbar.com/accessibility-weekly/coding-blockquotes/
npm package: @illinois-toolkit/ilw-spacer
Description: Illinois Toolkit: increase vertical margin between two other components
Latest version: 1.1.6

# ilw-spacer

Links: **[ilw-spacer in Builder](https://builder3.toolkit.illinois.edu/component/ilw-spacer/index.html)** | 
[Illinois Web Theme](https://webtheme.illinois.edu/) | 
[Toolkit Development](https://github.com/web-illinois/toolkit-management)

## Overview

This is a spacer component to increase vertical margin between two other components. This has one attribute that controls how tall this is in standard CSS height syntax. Defaults to 20px.

### Attributes
* `height`: height of spacer.

## Code Examples

```html
<ilw-spacer height="30px"></ilw-spacer>
```

## Accessibility Notes and Use

This generates a single `div` with no margins, padding-bottom of the height attribute, and a transparent color. 

This uses the `role="presentation"` attribute to ensure that screen readers and other assistive technology ignores it. This should not be in the accessibility tree.

## Upgrade Instructions

This is a new component. 

## External References

* https://developer.mozilla.org/en-US/docs/Learn/CSS/Building_blocks/Values_and_units
* https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/presentation_role
npm package: @illinois-toolkit/ilw-statistic
Description: Illinois Toolkit: display a statistic nicely in a web component.
Latest version: 1.1.0

# ilw-statistic

Links: **[ilw-statistic in Builder](https://builder3.toolkit.illinois.edu/component/ilw-statistic/index.html)** | 
[Illinois Web Theme](https://webtheme.illinois.edu/) | 
[Toolkit Development](https://github.com/web-illinois/toolkit-management)

## Overview

A statistic component is used to display significant data points. 

By default the card is a gray box with blue text. The box will fill the space of the container it is placed inside, but the text will stay centered.

- The top of the statistic can have a heading using `slot="top"`.
- Text can be resized to `small`, `medium`, `large` and `x-large` using `size="small"`.
- Color themes for `gray`, `blue`,`white`, and `blue-gradient`. For example, `theme="blue"`.

### Slots
| Slot  | Description |
| ------------- | ------------- |
| `slot="top"` | A piece of intro text, same style as the stat description text.  |
| `slot="stat"`  | Centered with larger text than the rest.  |
| `slot="source"`  | Italicized and slightly smaller text than the top and description text.  |

## Code Examples

```html
<ilw-statistic size="small" theme="gray">
  <span slot="top">Nation's</span>
  <span slot="stat">Top Six</span> Overall ranking among undergraduate programs in the U.S.
  <span slot="source">U.S. News and World 2022</span>
</ilw-statistic>
```

```html
<ilw-statistic size="large" theme="blue">
  <span slot="stat">#9</span> of students participate in research
</ilw-statistic>
```


## Accessibility Notes
- Ensure the slots are in order, top, stat and source.
- Spans are used to change the styling of each piece while containing the complete statistic in one block level element.

## External References

https://www.w3schools.com/tags/tag_span.asp
https://developer.mozilla.org/en-US/docs/Web/HTML/Element/span
npm package: @illinois-toolkit/ilw-tooltip
Description: Ilw-tooltip is a popup that provides additional information about a user interface element, such as a button or link, when the mouse hovers over it.
Latest version: 1.2.0

# ilw-tooltip

Links: **[ilw-tooltip in Builder](https://builder3.toolkit.illinois.edu/component/ilw-tooltip/index.html)** | 
[Illinois Web Theme](https://webtheme.illinois.edu/) | 
[Toolkit Development](https://github.com/web-illinois/toolkit-management)

## Overview

The Illinois theme component ilw-tooltip is a popup that provides additional information about a user interface element, such as a button or link, when the mouse hovers over it.
Tooltips are typically used to provide context or explanations for elements that may not be immediately clear to users.

The default color background color is white, there is also a blue option for the background.

The default position for the arrow is top center by default, but can be changed.

There is a slot for the tooltip trigger and a slot for the tooltip content.

### Attributes
* theme: Default is white background. Other theme available is ```blue```.

* arrow: The position of the arrow. Default is top center.

## Code Example

```html
<ilw-tooltip>
    <a href="javascript:void(0);" slot="trigger">Hover over me</a>
    <span slot="content">
        This is a simple tooltip example.
    </span>
</ilw-tooltip>

 <ilw-tooltip arrow="bottom-center">
    <a href="javascript:void(0);" slot="trigger">Hover over me</a>
    <span slot="content">
        <strong>Text can be bold.</strong><br>This is a tooltip example.
    </span>
</ilw-tooltip>

<ilw-tooltip theme="blue" arrow="bottom-left">
    <a href="#" slot="trigger" role="button">Hover over me</a>
    <span slot="content">
        Buttons can be used to trigger the tooltip.
    </span>
</ilw-tooltip>
```
## Code Example with Icon Button

```html
<ilw-tooltip theme="blue" arrow="bottom-left">
    <button slot="trigger" role="button">
        <ilw-icon size="50px" icon="admissions" alt="Admissions"></ilw-icon></button>
    <span slot="content">
        Admissions
    </span>
</ilw-tooltip>
    
```
## Accessibility Notes and Use

When placing tooltips, ensure that they do not obscure important content or navigation elements. Tooltips should be used to enhance the user experience by providing additional context without overwhelming the user.
The arrow position can be adjusted to ensure that the tooltip does not cover the element it is describing or get cut off by the edge of the viewport. Be sure to test on mobile.

## External References
- [WCAG Content on Hover or Focus](https://www.w3.org/WAI/WCAG22/Understanding/content-on-hover-or-focus.html)
- [APG Tooltip Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/tooltip/)
npm package: @illinois/react-use-local-storage
Description: React hook that persists and syncs state with local storage
Author: Nathan Walters
Latest version: 1.1.0

# react-use-local-storage

React hook that persists state with the [`localStorage`](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage) API. It also automatically syncs state between tabs/windows.

## Getting started

```
npm i @illinois/react-use-local-storage
```

This hook functions similarly to `useState`, with the exception of the the caveats listed below. If your state is easily encodable in JSON and you don't use lazy initialization or functional updates, it should be easy to migrate from `useState`. You'll need to provide a key for getting/setting the item in local storage.

```jsx
import useLocalStorage from '@illinois/react-use-local-storage'

const MyComponent = () => {
  const [count, setCount] = useLocalStorage('value-key', 0)
  return (
    <>
      <div>Count: {count}</div>
      <button onClick={() => setCount(count + 1)}>Increase</button>
      <button onClick={() => setCount(0)}>Reset</button>
    </>
  )
}
```

## Trying it out

```sh
git clone https://github.com/illinois/react-use-local-storage.git react-use-local-storage
cd react-use-local-storage
npm install
npm run storybook
```

This will launch a simple demo with a counter that can be incremented and reset. Try opening the demo in two tabs at once and watch how changes are automatically synced between them!

## Caveats/Warnings

* State is serialized with `JSON.stringify` and deserialized with `JSON.parse`. This is done because the `localStorage` API doesn't support storing anything but strings at present. As such, you should pay special attention to objects that might not handle being round-tripped through JSON, e.g. a `Date` object.

* Unlike `useState`, [lazy initialization](https://reactjs.org/docs/hooks-reference.html#lazy-initial-state) is not currently supported. A PR adding support would be welcome!

* Unlike `useState`, [functional updates](https://reactjs.org/docs/hooks-reference.html#functional-updates) are not currently supported. A PR adding support would be welcome!

## Prior art

* https://github.com/streamich/react-use/blob/master/docs/useLocalStorage.md
* https://github.com/rehooks/local-storage/blob/master/index.js