Bring the DataViews table, grid and new settings structure to Lite

[katie-2-0]

Document Library Pro now uses the new DataViews table and grid, and its settings pages were restructured in core 2.0.0. Please bring both into Document Library Lite.

If you're unsure how to structure anything, especially how Lite should consume dataviews-engine without bundling Pro code, check with @alessandrotesoro before you build it.

What should be free and what stays Pro-only

Free in Lite (fully working)

• Everything Lite has today, including the grid, image size and content length from 1.3.0
• The DataViews table and grid, replacing Simple_Document_Library and Simple_Document_Grid
• Infinite scroll, with the container height setting
• Multi-column sorting
• Unique URLs
• Sticky header and hide header
• The faster indexed search and loading
• The legacy frontend switch, so existing sites with custom CSS can go back to the old table

Pro-only

• All filters: filter dropdowns, multi-select filters, active filters, filter counts and filters in column headers
• Select all (it depends on multi-download, which is Pro)
• All Design tab options, including the new search, dropdown and checkbox colors
• Grid link options (grid_links, grid_document_title_link, grid_filename_link) and other link control
• Everything that is already Pro: folders, preview, multi-download, caching, extra columns, single document pages, search results page and so on

How Pro-only features appear in Lite

• Features people would realistically upgrade for (filters, folders, preview, multi-download, caching, design) stay visible but greyed out, with an upgrade link, as Lite does today.
• Small sub-options and minor tweaks are left out completely. Showing lots of disabled minor settings makes Lite look weak.
• Make sure Pro-only features can't be switched on through the shortcode either.

Implementation spec

The spec below maps every field in the new Pro settings pages and setup wizard to Free, Pro greyed or Omit. It also covers the engine architecture, shortcode args, settings migration and a QA checklist. It's meant as a starting point for your AI, not a final design. Anything marked as an open question needs Alessandro's input.

Two things to flag early:

• Lite doesn't currently detect Essentials or Advanced (it checks for an old Document_Library_Pro function), so both can run on one site. With the engine that would mean duplicate REST routes and index tables.
• In the DataViews frontend, filters are on unless two args are forced off, so Lite has to force them.

Full specification

Spec: DataViews frontend and new settings structure in Document Library Lite

Audience: an AI coding agent working in barn2plugins/document-library-lite. Read this whole file before writing code. Where this spec says "open question", stop and ask Alessandro (alessandrotesoro) instead of guessing.

1. Goal and sources of truth

Goal. Replace Lite's jQuery DataTables table and its separate grid with the DataViews frontend from barn2/dataviews-engine. Restructure Lite's settings pages and setup wizard so they match Document Library Pro tab by tab, section by section and field id by field id. Keep only the free feature set listed below. Keep Lite's old table behind a "legacy frontend" switch.

Refs read for this spec (2026-09-17):

Repo	Ref	Version	Use it for
document-library-core	origin/main 6029236	2.0.11	Settings tabs, View_Args, Options, Settings_Migration, Data_Source, Document_View, Frontend_Scripts
document-library-core	tag 1.1.7	last pre-DataViews	"New since 1.1.7" column below (git diff 1.1.7 origin/main -- src/Admin)
dataviews-engine	origin/main 45a47e1	1.0.24	src/View/View_Args.php defaults and validation, src/Config/Dataviews_Config_Builder.php, Engine, DVE_Installer, REST routes
document-library-essentials	origin/main 4608086	2.0.2	Scoping (.scoper.inc.php), service registration (src/Plugin.php), Settings_Controller, wizard steps, Update_Functions
document-library-advanced	origin/release/4.1.1 38166d2	4.1.1-rc2	Latest migration flow: Plugin::handle_2_0_0_migrate_settings() calling should_import_legacy_settings() and repair_settings()
settings-api	origin/main e9290f6		Field classes and React panel (what a field can and cannot do)
document-library-lite	main 3325b4f	1.3.0	Current Lite code

Copy structure from:

• Settings tabs: document-library-core/src/Admin/Settings_Tab/{Display,Search,Design,Single_Document,Advanced}.php plus document-library-essentials/src/Admin/Settings_Tab/General.php.
• Tab order and save sanitizing: document-library-essentials/src/Admin/Settings_Controller.php (General, Display, Search, Design, Single Document, Advanced).
• Wizard: document-library-essentials/src/Admin/Wizard/Setup_Wizard.php and Steps/*.
• Engine wiring: document-library-core/src/Engine_Service.php, src/Data_Source.php, src/View/*.

2. Architecture

2.1 How the plan plugins consume the engine today

• composer.json (require-dev): barn2/dataviews-engine ^1.0.10, barn2/document-library-core ^2.0.0, barn2/databasepress, barn2/databasepress-orm, barn2/settings-api ^0.5.0, barn2/setup-wizard ^1.3.0, barn2/barn2-lib ^2.4.3. Runtime require: woocommerce/action-scheduler ^3.9.
• .scoper.inc.php: php-scoper 0.18.0 prefixes everything into Barn2\Plugin\Document_Library_Essentials\Dependencies. A finder copies vendor/barn2/{document-library-core,dataviews-engine,databasepress,databasepress-orm} (*.php, *.js, *.css, *.json, *.png, *.svg, *.woff, *.woff2) and vendor/barn2/settings-api into dependencies/. Patchers:
  • strip the doubled Barn2 segment ({prefix}\Barn2\Data_Views becomes {prefix}\Data_Views);
  • rewrite engine hook names barn2_dataviews_* and posts_table_* to document_library_pro_*;
  • exclude Action Scheduler functions and classes from scoping.
• document-library-pro.php requires vendor/autoload.php and then vendor/woocommerce/action-scheduler/action-scheduler.php before services register.
• src/Plugin.php registers Document_Library_Core\Engine_Service (hooks init priority 5 and calls Engine::register( new Data_Source() )). On plugins_loaded priority 20 it calls DVE_Installer::install( 'dlp' ), which creates the index tables and queues the first index through Action Scheduler.
• Data_Source config: plugin_prefix dlp, hook_prefix document_library_pro, rest_namespace document-library-pro/v1, indexed_post_types dlp_document, searchable columns title, content, excerpt and the four document taxonomies.
• Frontend JS: core builds assets/js/dataviews.js from assets/js/src/dataviews/index.js using npm @barn2plugins/dataviews (repo barn2plugins/dataviews, GPL-3.0). Handles: dlp-dataviews and dlp-dataviews-style.
• Grid cards are server-rendered: Document_View::generate_card_html() uses Grid\Grid_Card.

2.2 How the legacy switch works in core (mirror this)

Piece	Behavior
Setting	legacy_frontend checkbox, Advanced tab, Advanced section. Engine default false.
Shortcode	legacy_frontend is a normal view arg (boolean).
Grid	View_Args::parse_args() and validate_dlp_args() force legacy_frontend = false when layout = grid. Grid is DataViews only.
Query	Document_View::create_query() returns Query\Legacy_Query if legacy, else View\View_Query (indexed).
Config	Document_View::create_config_builder() returns Config_Builder (DataTables) if legacy, else Dataviews_Config_Builder.
Assets	Frontend_Scripts::load_table_scripts() enqueues dlp-dataviews or the legacy DataTables handles.
Settings UI	Fields carry legacy_frontend conditions. DataViews only: multisort, select_all, filters_display, multiselect_filters, active_filters, filter_counts, unique_urls, infinite_scroll, infinite_height. Legacy only: filters, lazy_load, accent_neutralise, diacritics_sort. Pagination fields show when legacy is on OR infinite scroll is off.
Post limit	Engine: in DataViews mode (or lazy load) a post_limit equal to the site default means unlimited.
Upgrades	Essentials update_2_0_0_enable_legacy_frontend_for_upgrades and Advanced update_4_0_0_enable_legacy_frontend_for_upgrades set legacy_frontend = '1' for existing installs. Fresh installs get DataViews.
Wizard	Table step shows lazy_load only when legacy. Filters step shows filters (legacy) or filters_display (DataViews).

2.3 Recommended shape for Lite

1. Do not bundle document-library-core. Consume barn2/dataviews-engine (plus databasepress, databasepress-orm, settings-api, Action Scheduler) and port only the free classes from core into Lite's own namespace. Reason: core ships every Pro feature. WordPress.org guideline 5 bans locked trialware code in a free plugin, so switching Pro code off with arg forcing is not safe. Open question 1 confirms this with Alessandro.
2. Scoping. Add finders for vendor/barn2/{dataviews-engine,databasepress,databasepress-orm,settings-api} to Lite's .scoper.inc.php (prefix Barn2\Plugin\Document_Library\Dependencies). Copy Essentials' "double Barn2 namespace" patcher and its Action Scheduler excludes. The hook-prefix patcher needs a decision (open question 4).
3. Action Scheduler. Add woocommerce/action-scheduler and load it before services, as Essentials does.
4. Classes to port from core into Lite (trimmed to free features):

Core class	Lite version	Trim
Engine_Service	same	drop Legacy_Column_Config unless needed for Lite's old column syntax; keep WPML only if Lite supports it today
Data_Source	Data_Source	supported_columns = Lite columns (see 3.2); taxonomies and searchable_columns = only taxonomies Lite registers (doc_categories, file_type)
View\View_Args	View\View_Args	keep link and grid props needed for free features; apply the arg policy in section 4 inside parse_args()
View\Document_View	same	legacy branch returns Lite's Simple_Document_Library path (see 2.4)
View\Dataviews_Config_Builder	same	drop multi-download and select-all config
View\View_Query, View_Columns, View_Hooks, View_Factory	same	none expected
Data\Data_Factory + Table_Data/*	same	only Lite columns
Grid\Grid_Card	same	only Lite grid fields
Util\Options (parts)	extend Lite Util\Options	get_settings, update_settings, get_shortcode_options, sanitize_grid_content, normalize_grid_content, migrate_columns, migrate_link_style_settings, migrate_multicheckbox_settings, parse_*_from_v2_columns
Settings_Migration::convert_legacy_shortcode_settings(), repair_settings()	Lite Settings_Migration	see section 5
Frontend_Scripts (DataViews half)	extend Lite Frontend_Scripts	register dataviews.js and dataviews.css built in Lite from @barn2plugins/dataviews
assets/js/src/dataviews/index.js, assets/scss/dataviews.scss	copy	remove multi-download and FacetWP entries

5. Replace vs keep in Lite:

Lite file	Action
src/Simple_Document_Grid.php, assets/js/document-library-grid.js, assets/css/document-library-grid.css, wp_ajax_dll_load_grid in Table/Ajax_Handler.php	Remove. DataViews grid replaces it.
src/Simple_Document_Library.php, Table/Config_Builder.php, wp_ajax_dll_load_posts, DataTables assets	Keep. This becomes the legacy frontend.
src/Document_Library_Shortcode.php	Rewrite: build a Document_View via View_Factory::create(). Route to Simple_Document_Library only when legacy_frontend is true and layout = table.
src/Admin/Settings.php, src/Admin/Page/Settings.php, src/Admin/Settings_Tab/* (Settings_API_Helper)	Replace with a Settings_Controller built on barn2/settings-api Settings_Manager, like Essentials.
src/Admin/Wizard/Steps/*	Restructure (section 3.8).
src/Util/Options.php $readonly_settings, mark_readonly_settings()	Replace with a settings-api helper (section 3.1).
src/Post_Type.php, src/Taxonomies.php	Keep Lite's. Lite's post type is not public (public => false, rewrite => false) and Lite registers only doc_categories, file_type, document_download.

2.4 Legacy switch in Lite

• Add the legacy_frontend setting (Advanced tab) and shortcode arg with core's label and help text.
• Legacy on + table: render Lite's existing Simple_Document_Library markup, so existing custom CSS keeps working.
• Legacy on + grid: DataViews grid, same as core.
• Open question 2: should Lite's legacy be Lite's own Simple_Document_Library (recommended, protects custom CSS) or core's DataTables Config_Builder?
• Open question 3: should existing Lite installs start with legacy_frontend = 1 like Pro upgrades, or start on DataViews? The product owner's wording ("so existing Lite sites with custom CSS can go back") suggests DataViews by default. Pro does the opposite. Lite has no db_version option today, so detecting "existing install" needs a new marker. Check for dlp_shortcode_defaults.

2.5 Other open architecture points

• Pro detection is broken. src/Plugin.php::maybe_load_plugin() checks \Barn2\Plugin\Document_Library_Pro\document_library_pro. Essentials defines Barn2\Plugin\Document_Library_Essentials\document_library_pro and Advanced defines Barn2\Plugin\Document_Library_Advanced\document_library_pro. Nothing defines the old function, including inc/aliases.php. So Lite and a paid plan can load together today. With the engine that means two dlp_document data sources and possibly the same REST namespace. Fix before release (open question 5).
• Index tables and REST namespace. Reusing plugin_prefix = dlp lets an upgrade to Pro reuse the index. A separate prefix avoids clashes if both ever load (open question 6). Add the tables and options to Lite's uninstall.
• Text domains. Engine strings use dataviews-engine (99) and posts-table-pro (2). Scoped copies must be re-domained to document-library-lite for wordpress.org translations.
• wordpress.org source rule. @barn2plugins/dataviews lives in barn2plugins/dataviews. The built bundle needs public source or a link to it (open question 7).
• REST inputs. Rest/Routes/View_Data accepts filters, sorting, search, displayMode, includeFilterCounts, pagination.pageSize. In Lite, drop includeFilterCounts. Accept filters only for search-on-click columns. Clamp pageSize to the view's rows_per_page.

3. Settings pages

3.1 Conventions

• Option name: see open question 8. Recommended: the unified document-library-pro_settings (core Options::SETTINGS_KEY), written with Settings_Manager( $plugin, 'document-library-pro_settings' ), so an upgrade to Pro needs no import.
• Menu: keep Lite's document_library page slug.
• Free: same class, id, label, default and condition as core.
• Pro greyed: field is visible and cannot be changed. settings-api has no disabled or "pro" flag. The React panel spreads attributes onto Checkbox, Checkboxes, Color, Color_Size and Button inputs, so pass [ 'disabled' => 'disabled' ] there. Labels are plain text (decodeEntities). Descriptions and section descriptions run through html-react-parser, so put the "Pro version only" link in the description. Use Lite's existing URL: wordpress-plugins/document-library-pro/?utm_source=settings&utm_medium=settings&utm_campaign=settingsinline&utm_content=dlw-settings. Never save greyed values (strip in the barn2_settings_api_{slug}_save_settings filter).
• Omit: do not register the field. The runtime value is forced (section 4).
• "New" = field id not present at tag 1.1.7.
• Tab order: General, Display, Search, Design, Single Document, Advanced.

3.2 General tab (from Essentials Settings_Tab/General.php, not core)

#	Section	field id	label	Lite	New	Note
1	general	document_page	Document library page	Free		Lite has it today
2	general	license	License key	Omit		no license in Lite
3	document_data	document_fields	Document fields	Pro greyed		greyed in Lite today
4	document_data	document_slug	Document slug	Pro greyed		greyed today; single pages are Pro
5	version_control	version_control, version_control_mode	Enable / Replacing files	Pro greyed (section description only)		Lite shows section upsell today; Essentials does not add this section to its tab
6	frontend_submission	fronted_email_admin, fronted_moderation	Enable admin email / Enable moderation	Pro greyed (section description only)		upsell section today
7	lead_capture	lead_capture_*	(Advanced plan only)	Pro greyed (section description only)		upsell section today

3.3 Display tab (core Display.php)

#	Section (title)	field id	label	Lite	New	Note
1	display (no title)	layout	Default layout	Free		table, grid
2	table (Table)	columns	Columns	Free		Columns_Editor. Offer only Lite columns: id, title, content, image, date, doc_categories, link. Put Pro columns (excerpt, filename, file_size, file_type, doc_tags, doc_author, cf, download_count, status, date_modified, tax:*) in the description as a Pro link. The editor cannot grey single options (open question 9).
3	grid (Grid)	grid_content	Grid content	Free	changed	Core registers it twice with document_fields conditions (with and without excerpt). Lite options: image, title, excerpt (label "Excerpt/content"), doc_categories, link. Omit filename, file_type, file_size, download_count, doc_author, custom_fields (per-option disabling is not possible). Core requires at least one option (Settings_Controller validation).
4	grid	grid_links	Clickable fields	Omit		link control is Pro; minor option
5	grid	grid_columns	Number of columns	Free		autosize, 1 to 4
6	grid	grid_document_title_link	Document title	Omit		link control; Lite has no single pages
7	grid	grid_filename_link	Link destination	Omit		link control; filename field is Pro
8	sort_by (Sorting)	sort_by	Sort by	Free		Core adds name (Post slug), comment_count (Number of comments), custom (Other). Lite's legacy query allows only title, id, date, modified, menu_order, author, rand: see open question 10.
9	sort_by	sort_by_custom	Sort column	Free		shows when sort_by = custom
10	sort_by	sort_order	Sort direction	Free
11	sort_by	multisort	Multi-column sorting	Free	yes	DataViews only
12	download_button (Download button)	link_destination	Button behavior	Pro greyed		greyed today; ties to single document pages
13	download_button	link_style	Style	Free		values now button, file_icon, link
14	download_button	link_text	Button/link text	Free		hidden when file_icon
15	download_button	link_icon	Icon	Free		hidden when file_icon
16	download_button	link_target	New tab	Omit		minor link toggle
17	preview_button (Preview button)	preview	Enable preview?	Pro greyed		upgrade driver
18	preview_button	preview_style	Style	Omit		sub-option; the greyed toggle sells it
19	preview_button	preview_text	Button/link text	Omit		sub-option
20	preview_button	preview_icon	Icon	Omit		sub-option
21	multi_downloads (Multi-downloads)	multi_downloads	Allow multiple downloads?	Pro greyed		upgrade driver
22	multi_downloads	multi_download_text	Button text	Omit		sub-option
23	multi_downloads	multi_download_button	Button position	Omit		sub-option
24	multi_downloads	select_all	Select all	Omit	yes	depends on multi-download; minor
25	folders (Folders)	folders	Enable folders	Pro greyed		upgrade driver
26	folders	folders_order_by	Sort folders by	Omit		sub-option
27	folders	folder_status	Folder display	Omit		sub-option
28	folders	folder_status_custom	Custom	Omit		sub-option

3.4 Search tab (core Search.php, one section search)

Field order changed since 1.1.7. search_box moved from third to first.

#	field id	label	Lite	New	Note
1	search_box	Search box	Free	moved	Lite greys search_box today ($readonly_settings). The product owner made it free.
2	filters	Search filters	Pro greyed		legacy only condition
3	filters_display	Filter locations	Pro greyed	yes	DataViews only; options "Display filter dropdowns above the table", "Show filters in column headers"
4	filters_above	(Hidden)	Omit	yes	force false
5	filters_column	(Hidden)	Omit	yes	force false
6	filters_custom	(Filters_Editor, no label)	Omit		shows only when filters are on
7	multiselect_filters	Multi-select filters	Pro greyed	yes	distinct new capability worth showing
8	active_filters	Active filters	Omit	yes	minor display tweak of filters
9	filter_counts	Filter counts	Omit	yes	minor display tweak of filters
10	search_page	Search results	Pro greyed		greyed today; global search is a real feature

3.5 Design tab (core Design.php)

All fields are Pro. Recommended rendering: one Pro greyed panel per section (like Lite's current promo image, refreshed to show the new search, dropdown and checkbox colors) instead of about 60 disabled inputs. Do not register the fields. If Alessandro prefers disabled inputs, use the ids below in this order.

Section (title)	field ids in order (label)	New
design (no title)	description only
table_design (Table)	table_design (Design), default_table_template (Default table template), external_border (Borders: External), header_border (Header), border_horizontal_cell (Horizontal), border_vertical_cell (Vertical), border_bottom (Bottom), header_bg (Background colors: Header), body_bg (Main), body_bg_alt (Alternative), button_bg (Button), button_disabled_bg (Disabled button), button_bg_hover (Button hover), header_text (Fonts: Header), body_text (Main text), button_font (Button), disabled_button_font (Disabled button), hyperlink_font (Hyperlink), cell_backgrounds (Cell backgrounds), table_corner_style (Corner style), text_background (Search: Background), text_font (Font), text_border (Border), dropdown_background (Dropdown: Background), dropdown_font (Font), dropdown_border (Border), checkboxes_border (Checkboxes: Border), table_spacing (Spacing), reset_table_settings (Reset to the default)	new: text_background, text_font, text_border, checkboxes_border
grid_design (Grid)	grid_design (Design), default_grid_template (Default grid template), grid_image_bg (Background colors: Document image), grid_button_background (Button), grid_button_background_hover (Button hover), grid_card_background (Grid card), grid_category_bg (Category badge), grid_body_text (Fonts: Main text), grid_hyperlink_font (Hyperlink), grid_button_font (Button), grid_card_border (Borders: Grid card), grid_button_border (Button), grid_search_bg (Search: Background), grid_search_color (Font), grid_search_border (Border), grid_dropdown_bg (Dropdown: Background), grid_dropdown_color (Font), grid_dropdown_border (Border), grid_checkboxes_border (Checkboxes: Border), grid_corner_style (Corner style), reset_grid_settings (Reset to the default)	new: grid_search_bg, grid_search_color, grid_search_border, grid_dropdown_bg, grid_dropdown_color, grid_checkboxes_border
folder_design (Folders)	folder_design (Design), folder_icon_color (Top-level Folder color), folder_icon_subcolor (Sub-level folder color), folder_icon_svg_closed (Closed folder icon), folder_icon_svg_open (Open folder icon)

Labels written "Group: Item" are a group label on the first field and a sub-label (description slot) on the rest.

3.6 Single Document tab (core Single_Document.php, section single_document)

field id	label	Lite	Note
single_document_layout	Default layout	Pro greyed (tab promo panel)	Lite's post type is not public, so nothing here works in Lite. Keep the current promo.
single_document_layout_edit	(Button "Edit Layout")	Omit
single_document_fields	Display	Omit	registered twice in core (legacy vs block layouts)

3.7 Advanced tab (core Advanced.php)

#	Section (title)	field id	label	Lite	New	Note
1	advanced (no title)	content_length	Content length	Free
2	advanced	shortcodes	Shortcodes and media	Pro greyed		greyed today; embeds media in libraries
3	advanced	new_tab_links	Text links	Omit		Lite id was text_links_new_tab; minor link toggle
4	advanced	lightbox	Image lightbox	Free
5	advanced	unique_urls	Unique URLs	Free	yes	DataViews only
6	advanced	legacy_frontend	Frontend library	Free	yes	help: "Enable the legacy jQuery DataTables frontend"
7	table_options (Table options)	image_size	Image size	Free
8	table_options	lazy_load	Lazy load	Free	changed	now legacy only
9	table_options	accent_neutralise	Accent-insensitive search	Omit	changed	Lite id accent_insensitive; niche, legacy only
10	table_options	diacritics_sort	Diacritics sorting	Omit	changed	niche, legacy only
11	table_options	cache	Caching	Pro greyed		upgrade driver for big libraries
12	table_options	cache_expiry	Cache expires after	Omit		sub-option
13	table_options	clear_cache	Clear cache (Button)	Omit		sub-option
14	table_options	post_limit	Document limit	Omit		minor; DataViews treats the default as unlimited
15	table_options	responsive_display	Responsive display	Omit		minor; Lite offered one option only
16	pagination (Pagination)	rows_per_page	Documents per page	Free	changed	now hidden when infinite scroll is on (DataViews)
17	pagination	totals	Document total	Omit		minor position option
18	pagination	paging_type	Pagination style	Omit		minor style option
19	pagination	pagination	Pagination position	Omit		minor position option
20	pagination	page_length	Page length	Omit		minor position option
21	pagination	infinite_scroll	Infinite scroll	Free	yes	DataViews only
22	pagination	infinite_height	Container height	Free	yes	shows when infinite scroll is on

Not in any settings tab (shortcode only, all free): sticky_header, hide_header, wrap, scroll_offset, search_on_click (also stored per column by the columns editor).

3.8 Setup wizard

Pro step list (Essentials Setup_Wizard.php): License_Verification, Layout, Table (hidden), Grid (hidden), Filters (hidden), Upsell, Completed. Hidden steps are revealed by assets/js/admin/dlp-wizard-custom.js. Lite today: Welcome, Layout, Links, Behavior, Upsell, Completed. Lite already uses the setup-wizard premium => true field flag for greyed fields.

Step	field id	label	Lite	New	Note
License_Verification			Omit		keep Lite Welcome
Layout	layout	Default layout	Free
Layout	folders	Folders	Pro greyed (premium)		same as Lite today
Layout	preview	Document preview	Pro greyed (premium)		Lite has it in Links today
Table	columns	Columns	Free	changed	type document_columns replaces Lite's text field; Lite columns only
Table	multi_downloads	Multi-downloads	Pro greyed (premium)
Table	lazy_load	Lazy load	Free	changed	only when legacy
Grid	image, title, excerpt, doc_categories, link	Library content: Image, Title, Excerpt/content, Categories, Document link	Free	changed	replaces Lite's grid_content text field
Grid	filename, file_type, file_size, download_count, doc_author, custom_fields	Filename, File type, File size, Download count, Author, Custom fields	Omit		extra grid fields are Pro
Grid	grid_links	Clickable fields	Omit		link control
Grid	(Lite only) grid_columns	Number of columns	Free		not in Pro wizard; keep, limit to autosize and 1 to 4
Filters	filters / filters_display	Enable filter dropdowns / Filter locations	Pro greyed (premium)		move into the Layout step as one field, not a whole disabled step
Filters	filters_custom	(document_filters)	Omit
Links (Lite only)	link_text, link_style	Link text / Link style	Free		keep; map link_style options to button, file_icon, link plus link_icon
Behavior (Lite only)	lightbox, rows_per_page, sort_by, sort_order, lazy_load	Image lightbox / Documents per page / Sort by / Sort direction / Lazy load	Free		keep; move lazy_load to Table
Upsell, Completed			Free		keep Lite's

Fix while there: Lite Behavior::rows_per_page description reads "The text displayed on the button or link." (copy bug).

4. Shortcode and View_Args policy

Implement one Lite policy class, applied in Lite View_Args::parse_args() before parent::parse_args(), in Options::get_shortcode_options() and in the REST path. Stored values from a former Pro install must not switch anything on.

4.1 Accept (free)

Arg	Allowed values / note
layout	table, grid
columns (alias content)	Lite columns only; strip others
grid_content (alias content when grid)	image, title, excerpt (content maps to excerpt), doc_categories, link
grid_columns	autosize, 1 to 4; map 5 and 6 to 4
image_size, content_length, lightbox
search_box	checkbox, or top, bottom, both, false (engine accepts both)
search_on_click	bool or column list limited to doc_categories (and file_type if Lite adds the column)
sort_by, sort_order, multisort
rows_per_page (alias docs_per_page), post_limit (alias doc_limit)	post_limit stays shortcode-only
infinite_scroll, infinite_height
wrap, scroll_offset, sticky_header, hide_header
unique_urls, legacy_frontend
lazy_load	legacy only
link_style, link_text, link_icon	link_style: button, file_icon, link. Normalize old Lite values (icon, text, button_icon, button_icon_text, icon_only) with core Options::normalize_user_arguments() logic.
doc_category, status, date_format	Lite supports these today

4.2 Force (ignore user input)

Arg	Forced value
filters	false
filters_above, filters_column	false. Required: the engine defaults filters_above = true, and View_Args::resolve_non_legacy_filters() turns filters on in DataViews mode when either is true.
filters_custom	''
multiselect_filters, active_filters, filter_counts	false
folders	false (and all folder_*)
preview	false (and preview_style, preview_text, preview_icon)
multi_downloads, select_all	false
cache	false
shortcodes	false
link_destination	download_file
link_target, new_tab_links	false
document_link	true
links, grid_links	'' (open question 11: confirm the image lightbox and search-on-click still work with no link columns)
grid_document_title_link, grid_filename_link, table_document_title_link, table_filename_link	none
accent_neutralise, diacritics_sort	false
responsive_display	child_row
paging_type, totals, pagination, page_length	engine defaults (numbers, bottom, bottom, bottom), open question 12
widths, priorities, column_breakpoints, column_type, auto_width, responsive_control, date_columns, show_footer, reset_button, button_text, no_posts_message, no_posts_filtered_message, excerpt_length, show_hidden_columns, numeric_terms	engine defaults (Pro); open question 9 covers per-column widths from the columns editor
category, exclude_category, tag, term, exclude_term, cf, year, month, day, author, exclude, include, search_term, doc_tag, doc_author, exclude_doc_category	engine defaults (Pro; doc_tags and doc_author taxonomies are not registered in Lite)
post_type	dlp_document (as core Data_Source::get_default_args())

5. Settings migration

5.1 What Lite stores today

Option	Written by	Keys
dlp_shortcode_defaults	Display, Advanced tabs, wizard	Saves merge get_existing_shortcode_options() defaults, so most keys are present: link_text, lightbox, link_style, link_icon, layout, grid_columns, grid_content, image_size, rows_per_page, sort_by, sort_order, columns, content_length, lazy_load. Readonly fields are disabled, so they are never submitted.
dlp_document_fields	General tab (disabled)	editor, excerpt, thumbnail, comments map
dlp_document_page	General tab, activation	page ID
dlp_misc_settings	Advanced (cache_expiry, disabled)	usually empty

Lite defaults (Options::get_default_settings()): link_text Download, lightbox false, link_style button, link_icon false, layout table, grid_columns 4, grid_content image,title,content,link, image_size 70x70, rows_per_page 20, sort_by date, sort_order '', columns id,title,content,image,date,doc_categories,link, doc_category '', content_length 15, status publish, date_format Y/m/d, search_on_click true, wrap true, scroll_offset 15, post_limit 500, offset 0, lazy_load false.

Keep these as Lite's fresh-install defaults where they differ from core (lightbox, link_icon, rows_per_page, columns, grid_columns, date_format). Open question 13.

5.2 Mapping (Lite key to new key)

Core already does most of this. Settings_Migration::convert_legacy_shortcode_settings() reads dlp_shortcode_defaults (commit edffe07, "Fix Lite settings conversion", first in core 2.0.9). Reuse its logic; do not rewrite it.

Lite key	New key	Conversion (core helper)
layout	layout	unchanged
columns (CSV, col:Heading allowed)	columns (columns editor array)	Options::migrate_columns( $columns, $links = '', $link_destination = 'direct', $options ). Title gets link_destination = download_file; linkable columns get links = false; doc_categories gets search_on_click = true from Lite's default.
grid_content (CSV, uses content)	grid_content (selected list)	Options::normalize_grid_content() maps content to excerpt and drops unknown fields
grid_columns 1 to 6	grid_columns autosize or 1 to 4	convert_legacy_shortcode_settings() and repair_settings() map 5 and 6 to 4
link_style button, icon, text (wizard also button_icon_text, button_icon, icon_only)	link_style + link_icon + link_text	Options::migrate_link_style_settings(). If link_icon is already saved, the converter keeps the saved value.
link_text, link_icon	same	unchanged
(no links key in Lite)	grid_links = '', grid_document_title_link = none, grid_filename_link = none	converter default when links is empty
(no link_destination)	link_destination = download_file	converter default direct
lightbox, image_size, content_length, rows_per_page, sort_by, sort_order, lazy_load	same	checkbox booleans become '1' / '0' (update_2_0_0_migrate_settings() loop)
search_on_click, wrap, scroll_offset, post_limit, date_format, status, doc_category, offset	same (runtime args)	not settings fields; carry over or drop offset
text_links_new_tab, accent_insensitive, custom_filters, search_results_page	none	never saved (readonly); ignore
dlp_document_fields map	document_fields list	Options::migrate_multicheckbox_settings() in update_2_0_0_migrate_settings()
dlp_document_page	document_page	update_2_0_0_migrate_settings()
dlp_misc_settings	merged into settings	update_2_0_0_migrate_settings()

5.3 Flow

1. On init (after post type and taxonomy registration; Advanced uses priority 17), if the unified option has no user keys and dlp_shortcode_defaults is not empty (Settings_Migration::should_import_legacy_settings()), run the conversion once.
2. Always run Settings_Migration::repair_settings() afterwards (grid content normalization, 5 and 6 columns to 4).
3. Strip Pro-only keys before saving to Lite's option.
4. Leave dlp_shortcode_defaults in place for rollback and for the paid plugins' own import (open question 8).
5. Set legacy_frontend per open question 3.
6. Note: handle_fresh_v2_install() in update_2_0_0_migrate_settings() recreates empty legacy options. Check that this does not trip Lite's own "existing install" check.

6. Check with Alessandro

1. Bundle core with Pro features switched off, or port the free classes onto the engine only (recommended, because of wordpress.org guideline 5)?
2. Legacy frontend in Lite: Lite's Simple_Document_Library (recommended) or core's DataTables Config_Builder?
3. Existing Lite installs: default legacy_frontend on (as Pro upgrades) or off?
4. Scoper hook patcher: rename engine hooks to document_library_pro_* (shared with Pro snippets), to Lite's document_library_*, or leave as barn2_dataviews_*?
5. Fix Lite's Pro detection so it recognizes Essentials and Advanced (Barn2\Plugin\Document_Library_Essentials\document_library_pro, Barn2\Plugin\Document_Library_Advanced\document_library_pro). Should the paid plans also deactivate Lite?
6. Reuse plugin_prefix = dlp and document-library-pro/v1 in Lite, or give Lite its own?
7. How will the @barn2plugins/dataviews source be made available for wordpress.org review?
8. Store Lite settings in document-library-pro_settings (recommended) or keep dlp_shortcode_defaults? Advanced 4.1.1 imports from dlp_shortcode_defaults only when the unified option is empty.
9. DocumentColumnsEditor (@barn2plugins/components) has no props to hide or disable columns or per-column settings (widths, priorities, breakpoints, column type, links, link destination). Can it take a Lite mode, or should Lite filter options server-side and ignore those settings at runtime?
10. sort_by values name, comment_count and custom: free in Lite, or should Lite keep its current seven?
11. With links and grid_links empty, do the image lightbox and search-on-click still work in DataViews? Search-on-click renders a click-to-filter link (ClickableFilterCell). Does it work while the filtering feature is disabled, and how does a user clear that filter without active_filters?
12. Which pagination look Lite gets with paging_type, totals, pagination and page_length omitted.
13. Keep Lite's own defaults on fresh installs, or adopt core's?
14. Design tab: promo panel per section (recommended) or about 60 disabled inputs?
15. Action Scheduler and the index tables in a free plugin: any objections for hosts where WP-Cron is off, and should the index notice (Admin\Index_Status_Notice) show in Lite?

7. QA acceptance checklist

Upgrade from Lite 1.3.0

• A site with custom columns (including col:Heading), link_style = icon, rows_per_page = 10, lightbox = on keeps the same columns, headings, button look, page size and lightbox after upgrade.
• A grid set to 5 or 6 columns shows 4 columns, and settings show "4 columns".
• A grid with grid_content = image,title,content,link shows image, title, excerpt/content and link on DataViews cards.
• legacy_frontend has the value agreed in open question 3; switching it on brings back the old table markup, so existing custom CSS still applies.
• Layout grid with legacy on still renders the DataViews grid.
• dlp_shortcode_defaults still exists after migration.

Fresh install

• Wizard runs: Welcome, Layout (with greyed Folders, Preview, Search filters), Table, Grid, Links, Behavior, Upsell, Completed; values save.
• Documents are indexed (Action Scheduler job completes) and the library loads with search.

Free features (DataViews)

• Table and grid, grid columns autosize and 1 to 4.
• Search box on and off; search-on-click on categories filters the library and can be cleared.
• Single and multi-column sorting (multisort).
• Pagination with Documents per page; infinite scroll with container height (for example 500px, 70vh, calc(100vh - 200px)); an invalid height falls back to 70vh.
• Unique URLs: search, sort and page are in the URL, and reloading restores them.
• sticky_header, hide_header, wrap, scroll_offset work from the shortcode.
• Image size, content length, lazy load (legacy only), image lightbox.
• Link styles button, file type button and text link, with and without icon and custom text.

Pro features stay off

• Greyed fields cannot be changed and show a "Pro version only" link; saving never stores them.
• Omitted fields do not appear anywhere in settings or the wizard.
• [doc_library filters="true" filters_above="true" filters_column="true" multiselect_filters="true" active_filters="true" filter_counts="true"] shows no filters.
• [doc_library folders="true" preview="true" multi_downloads="true" select_all="true" cache="true" shortcodes="true"] shows none of these.
• [doc_library columns="title,file_size,doc_tags,cf:foo"] shows only title.
• [doc_library layout="grid" grid_content="title,filename,doc_author" grid_links="title" grid_document_title_link="single_document"] shows the title only, not linked.
• A REST view-data request with includeFilterCounts or a filter on a non search-on-click column returns no counts and ignores the filter.
• A settings option copied from a Pro site (filters, folders, design colors on) renders with all Pro features off and default design.

Coexistence and cleanup

• Lite with Essentials or Advanced active: Lite does not load, and there are no duplicate post type, REST route or index errors.
• Upgrade Lite to Essentials: Essentials shows Lite's migrated settings.
• Uninstall removes Lite's index tables, scheduled actions and options (per Lite's delete-data policy).
• No PHP notices with WP_DEBUG; no JS console errors on the settings page, wizard or frontend.
• All new strings use the document-library-lite text domain, including scoped engine strings.