# Styled XLSX 공용 모듈

[`assets/js/xlsx-export.js`](assets/js/xlsx-export.js)는 외부 라이브러리나 서버 API 없이
브라우저에서 실제 OpenXML `.xlsx` 파일을 생성하는 독립형 모듈입니다. 이 파일 하나만 다른
웹 프로젝트로 복사해 사용할 수 있습니다.

```html
<script src="/assets/js/xlsx-export.js"></script>
<script>
StyledXlsx.downloadWorkbook({
    applicationName: "My Web App",
    fileName: "inventory.xlsx",
    sheetName: "Inventory",
    title: "Inventory status",
    subtitle: "Filtered result · 2 rows",
    freezeColumns: 2,
    columns: [
        { header: "Part No", field: "partNo", width: 20, tone: "identity-accent" },
        { header: "Site", field: "site", width: 14, tone: "identity" },
        { header: "Quantity", field: "quantity", width: 13, type: "number", tone: "current" },
    ],
    rows: [
        { partNo: "001-A", site: "Korea", quantity: 1200.5 },
        { partNo: "=NOT_A_FORMULA", site: "USA", quantity: null },
    ],
    missingText: "—",
});
</script>
```

## 입력 계약

- `columns`: `header`, `field`, `width`, `type`, `tone`, `align`을 정의합니다.
- `type`: `text`, `integer`, `number` 중 하나입니다. 숫자형은 Excel의 실제 숫자 셀로 저장됩니다.
- `tone`: `identity`, `identity-accent`, `status`, `period`, `current`, `month` 중 하나입니다.
- `value(row, rowIndex)`: 원본 필드 대신 계산한 표시값을 내보낼 때 사용합니다.
- `cellTone(row, value, rowIndex)`: 상태 셀에 `success`, `warning`, `danger`를 적용합니다.
- `rowTone(row, rowIndex)`: 전체 행에 `warning` 또는 `danger`를 적용합니다.
- `freezeColumns`: 왼쪽에서 고정할 열 수입니다. 제목과 헤더 행은 항상 고정됩니다.
- `missingText`: `null`, `undefined`, 빈 문자열의 표시값입니다. 기본값은 빈 셀입니다.
- `columns[].missingText`: 특정 열의 누락 표시만 별도로 지정합니다.
- `applicationName`, `creator`, `footerText`: 파일 속성과 인쇄 바닥글 문구를 지정합니다.
- `maxCells`: 브라우저 보호용 셀 수 제한입니다. 기본 500,000셀, 최대 2,000,000셀입니다.
- `maxXmlCharacters`: 생성 XML 크기 제한입니다. 기본 32MB 상당, 최대 128MB 상당입니다.

문자열은 `inlineStr`로 기록하므로 `=`, `+`, `-`, `@`로 시작해도 수식으로 실행되지 않습니다.
열 너비, 제목·헤더 색, 교차 행, 상태색, 숫자 형식, 자동 필터, 고정창과 인쇄 설정이 포함됩니다.

## Tabulator 편의 함수

단순한 Tabulator 표는 표시 중인 열과 active 행을 자동으로 가져올 수 있습니다.

```js
StyledXlsx.downloadTabulator(table, {
    fileName: "table.xlsx",
    sheetName: "Data",
    title: "Current table",
    columnFactory(baseColumn, definition) {
        return definition.field === "quantity"
            ? { type: "number", tone: "period" }
            : baseColumn;
    },
});
```

`rowRange`는 기본 `active`이며, `includeColumn(definition, component)`으로 열을 제외할 수 있습니다.
점(`.`)으로 구분된 중첩 field도 읽습니다. `titleDownload`는 실행 가능한 HTML이 아니라 순수 텍스트로
취급합니다. accessor/formatter가 값을 크게 바꾸는 복합 표는 아래 명시적 Workbook 방식을 사용하세요.

복합 formatter 셀이나 업무별 집계표는 `downloadWorkbook()`에 열과 원본 행을 명시해 표시값과
서식을 통제하는 방식을 권장합니다. `createWorkbookBlob()`을 사용하면 자동 다운로드 없이 Blob만
생성할 수 있어 테스트, 업로드 또는 별도 저장 흐름에도 연결할 수 있습니다. `downloadWorkbook()`은
`{ blob, fileName }`을 반환하며, `StyledXlsx.mimeType`과 `StyledXlsx.version`도 제공합니다.

## 실행 환경과 용량

- TextEncoder, Blob URL, `anchor.download`를 지원하는 최신 Chrome/Edge/Firefox/Safari용 브라우저 모듈입니다.
  IE, Legacy Edge, Node/Worker, ES module import용 패키지는 아닙니다.
- 다운로드 호출은 클릭 같은 사용자 동작 안에서 실행하세요. sandbox iframe에서는 `allow-downloads`가 필요합니다.
- 생성과 ZIP 패키징은 브라우저 메인 스레드에서 동기 실행되며 ZIP은 호환성을 위해 무압축으로 저장됩니다.
  큰 표는 먼저 필터링하고, 기본 500,000셀·32MB XML 제한을 늘릴 때는 대상 브라우저 메모리를 확인하세요.
- `StyledXlsx` 전역이 이미 있으면 기존 객체를 덮어쓰지 않습니다. 한 페이지에서 모듈 파일은 한 번만 로드하세요.